Ferret MCP

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)

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

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:

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