Supermodel MCP Server

MCP server that provides deep codebase analysis to AI agents via the Supermodel API. Enables Claude to understand code structure, dependencies, and relationships by generating comprehensive graphs from any repository. Use this to help AI agents explore unfamiliar code, plan refactorings, assess change impact, and understand system architecture.

Install

npm install -g @supermodeltools/mcp-server

Or run directly:

npx @supermodeltools/mcp-server

Configuration

Get your API key from the Supermodel Dashboard.

| Variable | Description | |----------|-------------| | SUPERMODEL_API_KEY | Your Supermodel API key (required) | | SUPERMODEL_BASE_URL | Override API base URL (optional) |

Global Setup (Recommended)

Instead of adding your API key to each MCP config file, you can set it globally in your shell profile. This keeps your key in one place and automatically makes it available to all MCP clients.

For Zsh (macOS default):

Add to ~/.zshrc:

export SUPERMODEL_API_KEY="your-api-key"

For Bash:

Add to ~/.bashrc or ~/.bash_profile:

export SUPERMODEL_API_KEY="your-api-key"

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

With the API key set globally, you can omit the env block from your MCP configs:

{
  "mcpServers": {
    "supermodel": {
      "command": "npx",
      "args": ["-y", "@supermodeltools/mcp-server"]
    }
  }
}

Usage

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "supermodel": {
      "command": "npx",
      "args": ["-y", "@supermodeltools/mcp-server"],
      "env": {
        "SUPERMODEL_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "supermodel": {
      "command": "npx",
      "args": ["-y", "@supermodeltools/mcp-server"],
      "env": {
        "SUPERMODEL_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Add the MCP server with your API key:

claude mcp add supermodel --env SUPERMODEL_API_KEY=your-api-key -- npx -y @supermodeltools/mcp-server

Or if SUPERMODEL_API_KEY is already set in your shell environment:

claude mcp add supermodel -- npx -y @supermodeltools/mcp-server

Verify installation:

claude mcp list

Tools

analyze_codebase

Analyzes code structure, dependencies, and relationships across a repository. Use this to understand unfamiliar codebases, plan refactorings, assess change impact, or map system architecture.

When to use:

• Exploring new codebases
• Planning refactors or architectural changes
• Understanding dependencies between modules
• Mapping call relationships and code flow
• Assessing the impact of proposed changes

What you get:

• Dependency graphs (module/package relationships)
• Call graphs (function-level call hierarchies)
• Domain classifications (architectural patterns)
• AST relationships (structural analysis)
• Summary statistics (languages, complexity, file counts)

Parameters:

| Argument | Type | Required | Description | |----------|------|----------|-------------| | file | string | Yes | Path to repository ZIP file | | Idempotency-Key | string | Yes | Cache key in format {repo}:{type}:{hash} | | jq_filter | string | No | jq filter to extract specific data (strongly recommended) |

Quick start:

# 1. Create ZIP from your git repo
git archive -o /tmp/repo.zip HEAD

# 2. Get commit hash for cache key
git rev-parse --short HEAD
# Output: abc123

# 3. Ask Claude to analyze
# "Analyze the codebase at /tmp/repo.zip using key myproject:supermodel:abc123"

Example prompts:

• "Analyze the codebase at /tmp/repo.zip to understand its architecture"
• "Before I refactor the authentication module, analyze /tmp/repo.zip to show me what depends on it"
• "What's the structure of the codebase in /tmp/repo.zip?"

Troubleshooting

Debug logs go to stderr:

• [DEBUG] Server configuration: - Startup config
• [DEBUG] Making API request - Request details
• [ERROR] API call failed: - Error details with HTTP status

Common issues:

• 401: Check SUPERMODEL_API_KEY is set
• ZIP too large: Exclude node_modules/dist (use git archive)

Links

• API Documentation
• Supermodel SDK