Ferret

PyPI version Downloads License: MIT Python 3.12+ Tests

An MCP server that extracts complete knowledge from any codebase — architecture, patterns, dependencies, API surface. Combines static analysis with AI-powered deep interpretation.

Works with any MCP client: Claude Code, Claude Desktop, Cursor, and more.

Give it a repo, get a senior engineer's analysis in 30 seconds for ~$0.09.

Quickstart

Install & run with uvx (no clone needed)

uvx ferret-mcp

Or install with pip

pip install ferret-mcp

MCP Client Setup

Claude Code

claude mcp add ferret -- uvx ferret-mcp

To enable AI-powered tools (deep, ask), set your API key:

claude mcp add ferret -e FERRET_LLM_API_KEY=sk-ant-... -- uvx ferret-mcp

Claude Desktop / Cursor / Windsurf / any MCP client

Add to your MCP config file (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "ferret": {
      "command": "uvx",
      "args": ["ferret-mcp"],
      "env": {
        "FERRET_LLM_API_KEY": "sk-ant-..."
      }
    }
  }
}

Local development

git clone https://github.com/fabdendev/ferret-mcp.git
cd ferret-mcp
cp .env.example .env   # Add your API key
uv sync
uv run ferret-mcp

Tools

Static Analysis (free, no LLM required)

Tool	Description
scan	Repository overview — languages, structure, entry points, config files
dependencies	External packages + internal import graph with core modules
architecture	Layers, architectural patterns, module breakdown
patterns	Design patterns, naming conventions, testing, error handling
api_surface	REST endpoints, MCP tools, CLI commands, GraphQL, gRPC, exports
full_extraction	All of the above in one comprehensive report

AI-Powered (~$0.09/report with Haiku)

Tool	Description
deep	Comprehensive Knowledge Extraction Report — 10-section expert analysis covering architecture, data flow, strengths, risks, and learning takeaways
ask	Ask any question about a repo, answered with full codebase context

All tools take a path argument — the absolute path to the repository root directory.

Configuration

AI-powered tools (deep, ask) require an LLM. Configure via environment variables:

Env Var	Default	Description
FERRET_LLM_PROVIDER	anthropic	anthropic or openai (for Ollama, vLLM, LM Studio)
FERRET_LLM_MODEL	claude-haiku-4-5-20251001	Model name
FERRET_LLM_API_KEY	—	API key (required for Anthropic; ollama for local)
FERRET_LLM_BASE_URL	http://localhost:11434/v1	Base URL for OpenAI-compatible providers

Use with a local LLM (Ollama)

claude mcp add ferret \
  -e FERRET_LLM_PROVIDER=openai \
  -e FERRET_LLM_BASE_URL=http://localhost:11434/v1 \
  -e FERRET_LLM_MODEL=qwen3:8b \
  -- uvx ferret-mcp

Example Output

The deep tool produces a ~1000-line Knowledge Extraction Report covering:

1. Executive Summary — what it is, what stage, honest assessment
2. Architecture Deep Dive — patterns, modules, dependency direction, God Objects
3. Technology Stack & Rationale — why each choice was made
4. Data & Control Flow — ASCII diagrams, execution model
5. Design Patterns & Conventions — with file references
6. API & Interface Contracts — REST, CLI, MCP, auth model
7. Key Files Reading Guide — ordered reading path for new contributors
8. Strengths — what's genuinely well-designed
9. Risks & Technical Debt — brutal, specific, with fixes
10. Learning Takeaways — what to steal, what to avoid

Limitations

• .gitignore parsing only reads the root-level file (nested .gitignore files are not honored)
• Maximum 15,000 files scanned per repository
• File content analysis limited to files under 512 KB
• AI analysis quality depends on the LLM model used (Haiku is fast/cheap, Sonnet/Opus for deeper analysis)

License

MIT