Fossick
Search all of GitHub from your AI agent — find libraries, drill into repos, find code patterns.
Open source Open in the app JSON README (API)
About
Search all of GitHub from your AI agent — find libraries, drill into repos, find code patterns.
Details
- Kind
- MCP servers
- Topic
- Version control
- Publisher
- lipdog
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.4
- Stars
- 3
- Forks
- 1
- Last push
- 2026-04-13T22:34:36Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:01
- Updated
- 2026-08-29 03:02:01
- Origin id
io.github.Lipdog/fossick
README
<div align="center">
<img src="assets/logo.png" alt="Fossick" width="220" />
<h3>Prospect across all of GitHub from your AI agent.</h3>
<p><strong>Find libraries, discover gems, search code patterns, and read real production code — across 200M+ repos, PyPI, and npm.</strong></p>
<p>
<a href="https://pypi.org/project/fossick-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/fossick-mcp?color=blue&label=pypi"></a>
<a href="https://pypi.org/project/fossick-mcp/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/fossick-mcp?color=blue"></a>
<a href="https://github.com/Lipdog/fossick-mcp/actions/workflows/test.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/Lipdog/fossick-mcp/test.yml?branch=main&label=tests"></a>
<a href="https://github.com/Lipdog/fossick-mcp/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/Lipdog/fossick-mcp?color=blue"></a>
<a href="./LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-green"></a>
<a href="https://www.python.org/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11+-blue"></a>
<a href="https://modelcontextprotocol.io/"><img alt="MCP Protocol" src="https://img.shields.io/badge/MCP-1.0-orange"></a>
</p>
<p>
<a href="https://cursor.com/en/install-mcp?name=fossick&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmb3NzaWNrLW1jcCJdfQ%3D%3D"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg"></a>
<a href="https://insiders.vscode.dev/redirect/mcp/install?name=fossick&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22fossick-mcp%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white"></a>
</p>
</div>
---
## Contents
- [What is Fossick](#what-is-fossick)
- [Examples](#examples)
- [Installation](#installation)
- [Tools](#tools)
- [Why Fossick](#why-fossick)
- [FAQ](#faq)
- [Configuration](#configuration)
- [Development](#development)
- [License](#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:
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](https://docs.astral.sh/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](https://code.claude.com/docs/en/mcp)).
#### Global (recommended for personal use)
Available in **every project** on your machine. Stored in `~/.claude.json`, private to your user account.
```bash
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.
```bash
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.
```bash
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
```json
{
"mcpServers": {
"fossick": {
"command": "uvx",
"args": ["fossick-mcp"]
}
}
}
```
### Other clients
<details>
<summary><b>Cursor</b></summary>
[](https://cursor.com/en/install-mcp?name=fossick&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmb3NzaWNrLW1jcCJdfQ%3D%3D)
Or add manually to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
```json
{
"mcpServers": {
"fossick": {
"command": "uvx",
"args": ["fossick-mcp"]
}
}
}
```
</details>
<details>
<summary><b>VS Code</b></summary>
[](https://insiders.vscode.dev/redirect/mcp/install?name=fossick&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22fossick-mcp%22%5D%7D)
Or via CLI:
```bash
code --add-mcp '{"name":"fossick","command":"uvx","args":["fossick-mcp"]}'
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"fossick": {
"command": "uvx",
"args": ["fossick-mcp"]
}
}
}
```
Restart Claude Desktop after saving.
</details>
<details>
<summary><b>Windsurf</b></summary>
Edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"fossick": {
"command": "uvx",
"args": ["fossick-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Cline</b></summary>
Edit `cline_mcp_settings.json` via the Cline extension's MCP settings panel:
```json
{
"mcpServers": {
"fossick": {
"type": "stdio",
"command": "uvx",
"args": ["fossick-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Codex</b></summary>
```bash
codex mcp add fossick -- uvx fossick-mcp
```
Or edit `~/.codex/config.toml`:
```toml
[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]
```
</details>
<details>
<summary><b>From source (development)</b></summary>
```bash
git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync
```
Then point your MCP config at the local clone:
```json
{
"mcpServers": {
"fossick": {
"command": "uv",
"args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
}
}
}
```
</details>
---
## 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](https://github.com/github/github-mcp-server) when you also need to act on your own repos (issues, PRs, Actions).
---
## FAQ
<details>
<summary><b>Do I need a GitHub token?</b></summary>
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](https://cli.github.com/) and run `gh auth login` once. Fossick picks up your token automatically. No need to pass anything in the MCP config.
</details>
<details>
<summary><b>Why <code>uvx</code> instead of <code>pip install</code>?</b></summary>
`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.
</details>
<details>
<summary><b>Does Fossick use my GitHub API quota?</b></summary>
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.
</details>
<details>
<summary><b>Will it work with MCP client X?</b></summary>
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](#installation) section for client-specific snippets.
</details>
<details>
<summary><b>Does Fossick search private repos?</b></summary>
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.
</details>
<details>
<summary><b>Why doesn't it do <code>git blame</code> / PR history / version diffs?</b></summary>
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.
</details>
<details>
<summary><b>How fresh is the data?</b></summary>
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.
</details>
---
## 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](https://cli.github.com/) — **no config needed if you're already logged in**
To pass a token explicitly:
```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](https://docs.astral.sh/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`](./CLAUDE.md) for the full architecture tour, key patterns, and the recipe for adding new tools.
---
## Star history
<a href="https://star-history.com/#Lipdog/fossick-mcp&Date">
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Lipdog/fossick-mcp&type=Date" width="600" />
</a>
---
## License
[MIT](./LICENSE) — fossick away.
<!-- mcp-name: io.github.Lipdog/fossick -->