fastapi-mcp-server

---

⚡ Why this exists: Two Different MCP Paradigms

It is important to distinguish between two completely different uses of MCP with FastAPI:

Feature / Goal	fastapi-mcp (Execution Tool)	fastapi-mcp-server (Co-Developer Bridge)
Primary Goal	Enables AI to call live endpoints as runtime tools.	Enables AI to write, inspect, and synchronize code.
Server Requirement	Requires a running, live uvicorn instance.	Zero server needed: inspects local files on disk (or live URLs).
Pydantic Model Schemas	Only exposes parameters for executed calls.	Extracts full JSON schemas directly from Python BaseModel classes.
Frontend Code Gen	Not supported.	Directly outputs TypeScript interfaces & Zod validation schemas.
Project Auto-Discovery	Manual route registration.	AST scanner catalogs all apps, routers, and models automatically.
Ideal For	AI agents executing actions in production.	Developers & AI assistants writing frontend & backend code in IDEs.

---

🌟 Key Capabilities

1. Dual-Mode Introspection: Inspects local .py files directly from disk without running a server, or fetches live schemas from deployed staging/production URLs (https://api.example.com/openapi.json or http://localhost:8000/docs).
2. Instant TypeScript & Zod Generation: Converts Pydantic models and OpenAPI schemas into strict, copy-paste ready TypeScript interfaces and Zod validation schemas with full typing, nullability, and JSDoc comments.
3. Standalone Router & Sub-Module Support: Introspects full applications (main:app) as well as standalone APIRouter files (routers.users:router) and factory functions.
4. Project Auto-Discovery: Scans backend repositories using AST analysis to catalog every FastAPI app, router, and Pydantic model automatically.
5. Cross-Repository Context: Frontend developers working in a separate repository (e.g. Next.js/React) can point their IDE's MCP client to the backend project directory to inspect backend types while writing frontend code.

---

📦 Installation & Quickstart

Using uvx (Recommended — no installation needed)

uvx fastapi-mcp-server

Using pip

pip install fastapi-mcp-server

Running from source

git clone https://github.com/username/fastapi-mcp-server.git
cd fastapi-mcp-server
uv sync
uv run fastapi-mcp-server

---

🛠️ Editor & Client Configuration

Zed IDE

Add to your Zed settings.json (Ctrl + , or Cmd + ,):

{
  "context_servers": {
    "fastapi-mcp-server": {
      "command": {
        "path": "uvx",
        "args": ["fastapi-mcp-server"]
      }
    }
  }
}

For local workspace development without publishing:

{
  "context_servers": {
    "fastapi-mcp-server": {
      "command": {
        "path": "uv",
        "args": [
          "run",
          "--directory",
          "/path/to/fastapi-mcp-server",
          "fastapi-mcp-server"
        ]
      }
    }
  }
}

Cursor

Go to Cursor Settings > Features > MCP Servers > + Add New MCP Server:

• Name: fastapi-mcp-server
• Type: command
• Command: uvx fastapi-mcp-server

VS Code (with MCP / Copilot)

Add to your VS Code user or workspace settings (settings.json):

{
  "mcp": {
    "servers": {
      "fastapi-mcp-server": {
        "command": "uvx",
        "args": ["fastapi-mcp-server"]
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

---

🧰 Available MCP Tools

1. get_openapi_schema

Extracts the complete OpenAPI JSON schema from a local FastAPI app, standalone APIRouter, factory function, or live deployed HTTP URL.

• app_path (str, required): Import target (e.g. "main:app", "routers.users:router", "src/api.py:app") or live URL ("https://api.example.com/openapi.json", "http://localhost:8000/docs").
• project_dir (str, optional): Path to the backend project root.

2. get_pydantic_schema

Extracts the JSON Schema from any Pydantic BaseModel class (supporting both Pydantic v2 and v1).

• model_path (str, required): Import target (e.g. "models.user:UserProfile", "src/schemas.py:Item").
• project_dir (str, optional): Path to the backend project root.

3. list_registered_routes

Returns a structured catalog of registered routes, HTTP methods, operation IDs, summaries, and tags from an app, standalone router, or live URL.

• app_path (str, required): Target app, router, or URL.
• project_dir (str, optional): Path to the backend project root.

4. get_typescript_definition

Directly generates strict TypeScript interfaces and types from a Pydantic model, local app, or remote OpenAPI URL.

• target (str, required): Model target (e.g. "models.user:UserProfile"), app target ("main:app"), or live URL.
• project_dir (str, optional): Path to the backend project root.

5. get_zod_schema

Generates client-side Zod validation schemas (z.object({...})) and inferred TypeScript types from a Pydantic model or OpenAPI target.

• target (str, required): Model target, app target, or live URL.
• project_dir (str, optional): Path to the backend project root.

6. discover_fastapi_project

Scans a backend project directory using zero-execution AST parsing to catalog all FastAPI instances, APIRouters, and Pydantic models.

• project_dir (str, optional): Path to the project directory to scan.

---

🛡️ Error Handling

All tools return clean structured JSON dictionaries rather than raising unhandled exceptions or crashing the MCP connection:

{
  "error": "ModuleNotFoundError",
  "detail": "Failed to import module 'src.main'. Searched in sys.path: [...]"
}

---

🤝 Contributing

We welcome contributions! Please check out CONTRIBUTING.md for details on setting up the dev environment, running tests, and submitting PRs.

---

📄 License

MIT License. See LICENSE for details.