Fossick README | AllMCPs

Prospect across all of GitHub from your AI agent.

Find libraries, discover gems, search code patterns, and read real production code — across 200M+ repos, PyPI, and npm.

What is Fossick
Examples
Installation
Tools
Why Fossick
FAQ
Configuration
Development
License

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:

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.
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.
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).

Global (recommended for personal use)

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

Terminal

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.

Terminal

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.

Terminal

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

config.json

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

Other clients

Cursor

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

config.json

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

VS Code

Or via CLI:

bash

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

Claude Desktop

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

config.json

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

Restart Claude Desktop after saving.

Windsurf

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

config.json

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

Cline

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

config.json

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

Codex

bash

codex mcp add fossick -- uvx fossick-mcp

Or edit ~/.codex/config.toml:

toml

[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]

From source (development)

bash

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

Then point your MCP config at the local clone:

config.json

{
  "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

Do I need a GitHub token?

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.

Why uvx instead of pip install?

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.

Does Fossick use my GitHub API quota?

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.

Will it work with MCP client X?

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.

Does Fossick search private repos?

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.

Why doesn't it do git blame / PR history / version diffs?

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.

How fresh is the data?

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:

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

To pass a token explicitly:

config.json

{
  "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

bash

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):

bash

uv run fossick-mcp

Test

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

bash

uv run pytest

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

bash

uv run pytest -m live

Build

bash

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.

Prospect across all of GitHub from your AI agent.

Contents

What is Fossick

Examples

Discover libraries and packages

Drill into a specific repo

Find code patterns in the wild

Vet a dependency before adopting it

Installation

Claude Code

Global (recommended for personal use)

Team-shared (committed to git)

This project only (default)

Manual install

Other clients

Tools

Find candidates

Evaluate a candidate

Search code across GitHub

Why Fossick

FAQ

Configuration

Authentication

Rate limits

Development

Prerequisites

Setup

Run

Test

Build

Architecture

Star history

License