fossick-mcp 0.1.2

MCP server — search code, find libraries, and evaluate dependencies across all of GitHub, PyPI, and npm

Fossick MCP

Help your AI agent pick the right dependency — and learn from real code on GitHub.

Fossick is an MCP server that gives Claude, Cursor, and other LLM agents a focused toolkit for discovering libraries, evaluating them, and finding real-world code patterns across all 200M+ GitHub repos plus PyPI and npm. Seven read-only tools that answer two questions agents constantly run into: "what should I install for this?" and "how do real projects actually use this API?"

You: "I need a Rust TUI library — something newer than ratatui."

Agent: → search_repos(queries=["rust tui terminal", "rust terminal ui framework"],
                     language="Rust", stars="100..5000", pushed=">2026-02-01")
       → list_tags(repo=<top candidate>)        # still maintained?
       → repo_tree(repo=<top candidate>)        # what does it look like?
       → get_file(repo=<top candidate>, path="README.md")
       → search_code(query="<library>::App", language="Rust")  # real usage in the wild

       Here are 3 actively-maintained options with star counts, last release,
       and example usage from real repos…

Fossick is not for code archaeology — git history, blame, PR review, version diffing. Reach for git and gh CLI for that. Fossick exists for the moment you're starting something new and need to pick well.

Why Fossick

• Discovery-shaped, not search-shaped. Tools are designed around the workflow ("find candidate → check if it's alive → read the API → see how others use it"), not around exposing every GitHub endpoint.
• Hint chaining. Every response ends with suggested next steps (→ try repo_tree on this candidate), so the agent has a clear path forward without guessing.
• Multi-query search. search_repos accepts a list of phrasings in one call and reranks the merged results — better recall than running the same query three times.
• Tree-sitter symbol search. find_symbol runs real AST queries on fetched files instead of substring-matching, so "where is class Foo defined" actually returns the definition.
• Honest about rate limits. Tracks the GitHub Search and Core buckets separately, sleeps on exhaustion, retries with exponential backoff.
• Zero install for gh users. If you already have GitHub CLI authenticated, Fossick uses your token automatically.

Install

You'll need uv and Python 3.11+.

git clone https://github.com/Lipdog/fossick-mcp.git

Then add Fossick to your MCP client. The command is the same everywhere — just point --directory at your clone.

Claude Code

Add to your project's .mcp.json (or ~/.claude.json for global):

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

Authentication

Fossick resolves a GitHub token automatically, in this order:

1. GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN env vars
2. gh auth token from the GitHub CLI — no config needed if you're already logged in

To pass a token explicitly:

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

A token only needs the public read scope (no scopes selected is fine for public repos).

Tools

Seven tools, organized by their role in the discovery workflow.

Find candidates

Tool	What it does
search_repos	Discover repositories by topic, stars, language, recency, or trending. Accepts a list of query phrasings for better recall.
search_packages	Direct lookup on PyPI or npm when you already know the package name. Returns version, description, links, GitHub repo.

Evaluate a candidate

Tool	What it does
repo_tree	Browse a repo's file layout with depth and glob filtering.
get_file	Read any file at any branch, tag, or commit (READMEs, examples, the main module).
find_symbol	Goto-definition via tree-sitter — find where a class, function, or type is actually declared.
list_tags	View tags and recent releases. The fastest "is this still maintained?" check.

Search real code across GitHub

Tool	What it does
search_code	Search the contents of every public file on GitHub. Full search syntax (repo:, language:, path:, boolean operators, regex). Use it to find real-world examples of an API, locate config patterns (filename:Dockerfile FROM python), or scope a search to a single repo. The "show me how people actually do this" tool.

All tools are read-only, idempotent, and safe to auto-approve. Every response includes hint-chained next steps so the agent knows what to do next.

A typical session

"Find me a small, modern alternative to Pydantic for runtime validation in Python."

1. search_repos(queries=[
     "pydantic alternative validation",
     "dataclass runtime type validation",
     "lightweight schema validation python"
   ], language="Python", stars="100..5000")
   → ranked candidates with stars, descriptions, last-push dates

2. list_tags(repo=<top candidate>)
   → recent release dates — confirms it's actively maintained

3. get_file(repo=<top candidate>, path="README.md")
   → positioning, install instructions, code samples

4. search_code(query="from <pkg> import …", language="Python")
   → real adoption signal — who else is using it

5. find_symbol(repo=<top candidate>, name="Struct")
   → goto-definition for the core API — read it before adopting it

The agent can run the full evaluation in one turn without you context-switching to a browser.

Or, when you just want a code pattern:

"Show me how people set up structured logging with structlog and asyncio in production."

1. search_code(query="structlog configure_once asyncio", language="Python")
   → matches with surrounding context, ranked by file relevance

2. get_file(repo=<best match>, path=<file>)
   → read the full setup in context, not just the snippet

Rate limits

Fossick tracks both GitHub buckets independently and pauses when either is exhausted.

• Search API — 30/min: search_repos, search_code, find_symbol
• Core API — 5,000/hr: get_file, repo_tree, list_tags
• External APIs — search_packages hits PyPI / npm directly, no GitHub limit

Retries use exponential backoff on 403, 429, 502, 503. Search results are cached for 120s, branch content for 300s, SHA-pinned content for 1h.

Development

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync
uv run pytest                   # unit + registration (no network)
uv run pytest -m live           # integration tests against real GitHub
uv run fossick-mcp              # launch the server on stdio

The codebase is small and easy to navigate — see CLAUDE.md for an architecture tour and the recipe for adding a new tool.

Requirements

• Python 3.11+
• uv
• A GitHub token, or gh authenticated locally

License

MIT © 2026 Hayden Lipsky