Skip to main content
Glama
fossick-mcp
by Lipdog

Contents


Related MCP server: GitHub Activity MCP Server

What is Fossick

fossick /ˈfɒsɪk/ verb (Australian/NZ) — to prospect or rummage for gems, especially the small-scale kind of mining where you sift creek beds and old tailings looking for what bigger operators missed.

That's exactly what this tool does — but for code.

Fossick gives your AI agent seven read-only tools to prospect across all of GitHub, PyPI, and npm, covering the full discovery loop end-to-end:

  1. Search and discover. Sift 200M+ repos with multi-query relevance ranking, find the small-but-good libraries that bigger tools bury, look up packages on PyPI and npm.

  2. Drill into any repo without cloning. Browse a remote repo's tree with depth and glob filters, read any file at any branch/tag/commit, and goto-definition for any class, function, or type — all on remote GitHub, no local checkout needed.

  3. Search code patterns across all of GitHub. Full-text, regex, qualifier-aware search across every public file — find how an API is actually used in production, not just in the docs.

Useful any time you'd benefit from your agent reaching into the world's largest code corpus:

  • Pick the right library. Find a small, focused, actively-maintained option for any task — not just the most popular one.

  • Discover hidden gems. Surface the 500-star library that ranks higher on relevance than the 50,000-star incumbent.

  • Drill into a repo you found. Walk its layout, read its README, find where its core API is defined — without git clone.

  • Find usage patterns in real code. Search how an API is called in production, then read the matched files in context.

  • Get inspired. See how others structured similar projects, what patterns they used, what tradeoffs they made.

  • Stay current. Discover what's trending, just-released, or new in an ecosystem — past your model's training cutoff.

It does not do code archaeology — git blame, PR history, version diffs. Reach for git and gh for that.


Examples

Once Fossick is connected, here's the kind of thing you can ask your agent.

Discover libraries and packages

  • "Find me a small, actively-maintained Rust TUI library — something newer than ratatui."

  • "What are people using instead of LangChain these days?"

  • "Show me trending Python web frameworks released in the last 90 days."

  • "What's a good lightweight alternative to Pydantic for runtime validation?"

Drill into a specific repo

  • "Browse the structure of astral-sh/uv — what's in crates/?"

  • "Read the main __init__.py from pydantic/pydantic."

  • "Where is the Stream class defined in anthropics/anthropic-sdk-python?"

  • "What's the latest release of modelcontextprotocol/python-sdk and when did it ship?"

Find code patterns in the wild

  • "How do production FastAPI apps actually set up structured logging with structlog and asyncio?"

  • "Show me real examples of tokio::select! being used with timeout cancellation."

  • "Find Dockerfiles that build multi-stage Python images with uv."

  • "How are people calling the OpenAI API streaming endpoint from Go?"

Vet a dependency before adopting it

  • "Is the requests library still maintained?"

  • "Compare freshness of httpx vs aiohttp — last release dates, recent activity."

  • "Who actually uses msgspec? Show me real usage in production codebases."

  • "Find the GitHub repo behind the polars PyPI package and check its last release."


Installation

Prerequisite: uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh. Then uvx will download and run Fossick on demand. No clone needed.

Claude Code

Three install scopes. Pick the one that matches how you want Fossick to be available — globally, shared with your team, or just for you in one project. The scope flag controls where the config gets written (Claude Code MCP scopes).

Available in every project on your machine. Stored in ~/.claude.json, private to your user account.

claude mcp add fossick --scope user uvx fossick-mcp

Team-shared (committed to git)

Stored in .mcp.json at the project root, checked into version control. Anyone who clones the repo gets the same MCP server. Use this when the whole team should have Fossick.

claude mcp add fossick --scope project uvx fossick-mcp

This project only (default)

Local scope is the default. Only enabled in the current project, only for you. Stored in ~/.claude.json under this project's path — not committed, not shared with collaborators.

claude mcp add fossick uvx fossick-mcp

Manual install

If you'd rather skip the CLI, write the config yourself. The JSON shape is the same regardless of scope — only the file changes:

  • ~/.claude.json for user / local scope

  • .mcp.json (project root) for project scope

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Other clients

Install in Cursor

Or add manually to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Install in VS Code

Or via CLI:

code --add-mcp '{"name":"fossick","command":"uvx","args":["fossick-mcp"]}'

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

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Edit cline_mcp_settings.json via the Cline extension's MCP settings panel:

{
  "mcpServers": {
    "fossick": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}
codex mcp add fossick -- uvx fossick-mcp

Or edit ~/.codex/config.toml:

[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]
git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

Then point your MCP config at the local clone:

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

Tools

Seven read-only 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. Pass multiple query phrasings in one call for better recall.

search_packages

Direct lookup on PyPI or npm by package name. Returns version, description, links, and GitHub repo URL.

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.

find_symbol

Goto-definition via real AST queries — find where a class, function, or type is actually declared, not just substring-matched.

list_tags

View tags and recent releases. The fastest "is this still maintained?" check.

Search code across GitHub

Tool

What it does

search_code

Full-text search across every public file on GitHub. Supports repo:, language:, path:, boolean operators, and regex. Find real-world usage patterns, config examples, or anything else in the world's largest code corpus.

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


Why Fossick

  • Built for the discovery workflow. Tools follow the natural shape: find candidate → drill into it → read the API → see how others use it. Hint-chained next-step suggestions keep your agent on rails through the whole loop.

  • Drill into any public repo without cloning. Browse remote repo trees with depth + glob filters, read any file at any branch/tag/commit, and run real AST-based symbol search to goto-definition for any class, function, or type — all on remote GitHub.

  • Multi-query search with smart ranking. search_repos accepts a list of phrasings in one call and applies composite relevance ranking that prioritizes literal match over raw popularity — surfaces the 500-star gem that beats the 50,000-star incumbent.

  • Lean on tokens by design. 7 focused tools (not 30+), formatted-markdown outputs (not JSON dumps), TTL caching, hint chaining that cuts agent reasoning turns, and multi-query search that bundles N requests into 1. Every tool description and response is sized to keep your context budget free for real work.

  • Rate-limit aware. Tracks GitHub's Search and Core API buckets separately, sleeps on exhaustion, retries with exponential backoff.

  • Zero config for gh users. Already have the GitHub CLI authenticated? Nothing to configure.

  • Plays well with others. Read-only, idempotent, safe to auto-approve. Pair Fossick with github-mcp-server when you also need to act on your own repos (issues, PRs, Actions).


FAQ

Yes — without one you'll hit GitHub's 60-requests-per-hour unauthenticated limit almost immediately. The easiest path is to install the GitHub CLI and run gh auth login once. Fossick picks up your token automatically. No need to pass anything in the MCP config.

uvx runs Fossick in a transient, isolated environment without polluting your global Python. It downloads on first use, caches for subsequent runs, and updates effortlessly. You also don't need to manage a virtualenv or worry about Python version conflicts. If you'd rather use pip, pip install fossick-mcp works — just point your MCP client at the installed fossick-mcp binary.

Yes. Every search, file fetch, and tag list counts against your token's rate limits. Fossick splits requests across two buckets — Search API (30/min) and Core API (5,000/hr) — and pauses automatically when either is exhausted. For most discovery sessions you'll never hit the limits.

If your client supports the standard MCP stdio transport, yes. The standard uvx fossick-mcp config works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Codex, and most others. See the Installation section for client-specific snippets.

Only those your GitHub token can access. The token's permissions are the only constraint — Fossick doesn't have its own ACL layer. If your token can read a private repo, Fossick can search it; if not, it can't.

Deliberate scope decision. Code archaeology (who changed what, why, when) is a different shape of problem and is well-served by git and the gh CLI. Fossick stays focused on the discovery workflow — finding and evaluating, not investigating.

Live from GitHub on every request. Fossick caches results briefly to avoid hammering the API on repeated identical calls, with longer TTLs for content pinned to a specific commit SHA. Anything past the TTL is a fresh fetch.


Configuration

Authentication

Fossick resolves a GitHub token automatically:

  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": "uvx",
      "args": ["fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

A token only needs public repo read access (no scopes selected is fine).

Rate limits

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

Bucket

Limit

Tools

Search API

30 req/min

search_repos, search_code, find_symbol

Core API

5,000 req/hr

get_file, repo_tree, list_tags

External

No GitHub limit

search_packages (hits PyPI/npm directly)

Retries use exponential backoff on rate-limited and transient errors. Results are cached briefly to avoid redundant API calls, with longer TTLs for content pinned to a specific commit SHA.


Development

Prerequisites

  • Python 3.11+

  • uv

Setup

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

Run

Launch the MCP server on stdio (for manual testing or local MCP-client config):

uv run fossick-mcp

Test

Unit and registration tests — no network, runs in seconds:

uv run pytest

Live integration tests — hits real GitHub against pinned modelcontextprotocol/python-sdk@v1.14.0:

uv run pytest -m live

Build

uv build

Produces dist/fossick_mcp-<version>.tar.gz and the corresponding wheel.

Architecture

See CLAUDE.md for the full architecture tour, key patterns, and the recipe for adding new tools.


Star history


License

MIT — fossick away.

Available Tools

7 tools
find_symbolA
Read-onlyIdempotent

Goto-definition: find where a symbol is defined in one repo or across all of GitHub.

How it works: queries GitHub's code-search index for files containing
the symbol name, parallel-fetches the top ~15 candidate files, parses
each with tree-sitter, and queries the AST for declaration nodes
(class, function, struct, trait, interface, etc.) whose name matches
exactly. Results are ranked with type-declaring kinds
(class/struct/trait) first, then functions, then methods, then
variables. Success responses include real absolute line numbers and
ripgrep-style context (2 lines above, match line, 5 lines below)
pulled from the full file, not GitHub's 3-line fragment.

Languages with AST-precise matching via tree-sitter: Python, JavaScript,
TypeScript, Go, Rust, Java, Ruby, C, C++. Other languages fall back to
a regex-on-fragment path that is less precise but still useful.

Best for **distinctive** symbol names — `FastMCP`, `DataLoader`,
`ClaudeAgentOptions`, `Runtime`, `Tokenizer`. These are names creators
chose to be findable, and the first-declaration-wins ranking is
almost always right.

NOT for generic names like `connect`, `handle`, `init`, `get`, `run`
that show up in every library. GitHub's text-relevance ranking puts
usage-heavy files above the one declaring them, so the declaration
file often isn't in the top 15 we fetch. For generic names, use
`search_code` with disambiguating keywords (e.g.
`search_code("export function connect", repo="reduxjs/react-redux")`)
or combine with `path:` qualifier to narrow the search.

NOT for finding call-sites or usage patterns — use `search_code`
with the symbol name and a `repo:` qualifier for that.

Inputs: name (required), repo, language, kind, +3 more.

get_fileA
Read-onlyIdempotent

Read file content from one file in a GitHub repository. Returns full file with line numbers, supports line range slicing (start_line/end_line) and substring/regex match filtering with context lines. Truncates files over 500 lines unless a range or match is specified. Use after locating a file via search_code, find_symbol, or repo_tree.

Inputs: repo (required), path (required), ref, start_line, +3 more.

list_tagsA
Read-onlyIdempotent

List tags or releases for one repository. Default mode returns lightweight tag names with commit SHAs. Release mode (releases=true) returns full release objects including tag name, title, changelog body, publish date, and attached assets. Use to check a library's freshness (is it actively maintained?), find the current version to pin against, or pick a specific release to read files at via get_file(ref=) or browse via repo_tree(ref=).

Inputs: repo (required), releases, page, per_page.

repo_treeA
Read-onlyIdempotent

View the file tree of a GitHub repository or subdirectory. Recursive listing with depth control (1-3 levels), glob pattern filtering (e.g. *.py), and optional file sizes. Automatically filters noise directories (node_modules, pycache, .venv, dist, etc.). Use to understand project layout and discover key files before reading them with get_file.

Inputs: repo (required), path, ref, depth, +2 more.

search_codeA
Read-onlyIdempotent

Search for code across all of GitHub (200M+ repos), or narrowed to one repo/org/path. Supports regex (/pattern/), tree-sitter symbol search (symbol:name), boolean operators (AND/OR/NOT), exact phrases, and code-search qualifiers: repo:, org:, user:, path:, language:, content:, symbol:, is:archived, is:fork, is:vendored, is:generated, size:, in:file, in:path, filename:, extension:. Convenience params repo, language, path are appended as qualifiers automatically. Use this to find real-world usage patterns (how do projects actually import and call library X?), discover who uses a library (search for its import/crate name across GitHub), or locate example code for a framework you're evaluating. NOT for finding where a symbol is defined (use find_symbol). IMPORTANT: GitHub's code-search endpoint does NOT support repository-level qualifiers like stars:, pushed:, forks:, created:, topic:, license:, archived: — GitHub silently matches them as literal file content, giving wrong results with no error. For popularity-filtered discovery, use search_repos instead.

Inputs: query (required), repo, language, path, +3 more.

search_packagesA
Read-onlyIdempotent

Search for a package on PyPI or npm (not GitHub — does not use GitHub API or rate limits). PyPI: exact-match lookup returning version, description, license, homepage, and GitHub URL. npm: text search returning multiple results with links. Use for looking up package metadata and versions — chain with search_repos to explore the source repository.

Inputs: name (required), ecosystem, limit.

search_reposA
Read-onlyIdempotent

Discover GitHub repositories — the go-to tool for finding real, maintained, coherent repos during a coding session. Optimized for "find reference implementations / prior art / learning material / small-but-quality gems in an ecosystem," NOT for "rank by raw popularity." Returns per-result: name, full description, topics, primary language, star count, last-push date, license, homepage, and archived status.

Dev-session use cases this serves well:
  • "Rust agent harness — what are my options?" — finds frameworks/harnesses ranked by literal relevance, not star count
  • "Python async rate limiter — show me existing libraries" — dedicated libs beat big frameworks
  • "What's the landscape of LLM observability tools?" — surfaces the actual category leaders
  • "Is there already a tool for managing Claude Code sessions?" — hyper-specific gem hunting, small focused CLIs float up
  • "What's new in this ecosystem this week?" — set `trending=True` for repos created in the last 7 days
  • "Disambiguate a name the user mentioned" — one-hop metadata lookup

Ranking (multi-query mode): composite relevance score combining literal description match × 3, topic-tag match × 2, cross-phrasing robustness × 2, recency bonus (0-3), and log-scaled stars at half-weight. Stars are a TIEBREAK, not a driver — this is why a 500-star literal-match repo can outrank a 40,000-star repo that doesn't contain the query terms in its description. Tested against 6 dev-session queries in benchmarks/rank_experiment.py; composite scoring produced the best top-5 on 5/6 queries and consistently surfaced small-but-quality gems that star-first ranking buried.

Query sharpness — most→least noisy:
  • `topic:X` — self-assigned tags. Noisy for umbrella terms (e.g. `topic:mcp` returns opportunistic taggers like n8n). Sharp for tight niches (`topic:ratatui`).
  • `in:readme "phrase"` — matches any mention in the README. Medium.
  • `in:description "phrase"` — matches repos whose short description contains the phrase. Sharpest, but note that GitHub does literal substring matching — so `"embeddings database"` will also match "embedded database" (burned in testing). Prefer specific, domain-meaningful phrases.

SHORTLISTING — always use `queries=[...]` with 2-4 phrasings. Single-phrase `in:description` is sharp but narrow; popular options routinely describe themselves with different wording. For example, `in:description "Postgres operator"` returns Zalando's postgres-operator (5k★) but misses CloudNativePG (8k★), which describes itself as "Kubernetes-native PostgreSQL." Passing both phrasings via `queries=` runs them in parallel, dedupes by repo, and annotates each result with `matched K/N`. Recipe for concept X in language L: `queries=['in:description "X" language:L', 'in:description "X synonym" language:L', 'topic:X-slug language:L']`.

Other tips: keep queries short (GitHub uses AND logic — more terms = fewer results). Use the `language` filter instead of putting the language in the query. Use `archived:false` to exclude abandoned repos. Use `pushed:>YYYY-MM-DD` to filter by activity. For strict popularity filtering (production dependency shortlisting), add `stars:>N` explicitly — the tool no longer applies a star floor by default because gem-finding needs to see small repos.

NOT for: searching code inside repos (use `search_code`), fetching a repo you already know by name (use `get_file`/`repo_tree`), or authoritative library popularity (check package registries via `search_packages`).

IMPORTANT: repo search does NOT support file-level qualifiers like path:, filename:, extension:, content:, symbol: — GitHub silently matches them as literal content, giving misleading results with no error. Use `search_code` for those.

Inputs: query, queries, topic, language, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct purpose: find_symbol finds definitions, get_file reads files, list_tags lists releases, repo_tree shows directory structure, search_code searches code, search_packages queries package registries, and search_repos discovers repositories. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern with snake_case: find_symbol, get_file, list_tags, repo_tree, search_code, search_packages, search_repos. The naming is uniform and predictable.

    Tool Count5/5

    With 7 tools, the set is well-scoped for a code exploration server. It covers the core tasks of finding, reading, searching, and browsing code and repositories without being bloated or sparse.

    Completeness4/5

    The tool surface is largely complete for read-only exploration: symbol lookup, file reading, directory browsing, tag listing, and three types of search (code, packages, repos). Missing are operations like viewing commit history or blaming, which are secondary to the server's focus.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search and retrieve context from GitHub issues, pull requests, releases, and documentation using hybrid semantic search and time-ordered activity scans.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding assistants to inspect local and remote repositories through sandboxed tools that surface project overviews, structure, dependency audits, Git churn hotspots, and a heuristic health score. It also supports safe GitHub issue searching and creation with built-in duplicate preflight checks, while blocking sensitive files, binary content, and path traversal attacks.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to analyze public GitHub repositories directly through tools for repo health scoring, recent commit summaries, good first issue discovery, and semantic Q&A over docs and issues.
      4
      31 npm
      1
      MIT