Skip to main content
Glama
FastAPI Architect MCP

FastAPI Architect MCP

fastapi-architect-mcp

An MCP server that gives Claude Code IDE-level intelligence for FastAPI projects — semantic code navigation, safe renaming, route inspection, dependency trees, Pydantic model analysis, and a typed knowledge graph of the whole application.

Instead of Claude reading files blindly, it calls structured tools backed by Jedi (Python language server) and Python's AST.

Tools

Tool

Description

find_references

Find all usages of a symbol across the project

rename_symbol

Safely rename a symbol across all files

go_to_definition

Jump to where a symbol is defined

get_completions

Get completion suggestions at a cursor position

list_routes

List all FastAPI routes with their full paths (router prefixes applied)

get_dependencies

Get the full injection tree for a handler (router, decorator and signature Depends())

build_dependency_graph

Per-file view: route → input models → dependencies → response model

validate_response_models

Detect routes missing a response_model declaration

list_models

List all Pydantic/SQLModel models in a file

inspect_model

Inspect a model's fields, types, defaults, and validators

find_model_usages

Find everywhere a model is used across the project

detect_schema_orm_mismatches

Detect field mismatches between ORM model and Pydantic schema

Knowledge graph

Tool

Description

build_knowledge_graph

Build or refresh the project graph and return its statistics

graph_report

Markdown overview: routes with their auth, most connected symbols, tables, audit findings

graph_neighbors

Explore what a route, function, model or table uses and is used by

impact_analysis

Everything affected if a symbol changes, with the chain explaining each impacted route

find_path

Shortest paths between two nodes, e.g. from a route to a SQL table

audit_graph

Write routes without auth, duplicate or unmounted routes, unused schemas, unreferenced ORM models, dependency cycles

export_graph_html

Standalone interactive HTML visualization of the graph

Related MCP server: PyEye Server

Knowledge graph

The graph is built statically from the AST — no code is executed and no LLM is involved.

Nodes: App, Router, Route, Handler, Dependency, Middleware, Function, Schema, ORMModel, Class, Table, Template, Module

Edges:

App/Router ──INCLUDES──▶ Router          (prefixes → full route paths)
Route ──HANDLED_BY──▶ Handler
Route/Router/function ──DEPENDS_ON──▶ Dependency
function ──ACCEPTS / RETURNS──▶ Schema/ORMModel
function ──CALLS──▶ function             function/class ──USES──▶ class
function ──QUERIES──▶ Table              (raw SQL strings: SELECT, INSERT, UPDATE, DELETE, CREATE)
function ──RENDERS──▶ Template           App ──MIDDLEWARE──▶ Middleware
ORMModel ──MAPS_TO / REFERENCES──▶ Table ORMModel ──RELATES_TO──▶ ORMModel
Schema ──INHERITS──▶ Schema              Schema ──MIRRORS──▶ ORMModel (name + field overlap, with confidence)

It covers both structured projects (APIRouter, Depends, SQLAlchemy/SQLModel) and flat ones (a single main.py, raw psycopg2 queries, Jinja2 templates, manual auth checks).

Cache: per-file extraction results are stored in <project>/.fastapi-architect/graph.json (git-ignored automatically). Only new or modified files are re-parsed, so graph tools stay fast after the first build.

Installation

pip install fastapi-architect-mcp

Configuration

Option 1 — Global (available in all projects)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "fastapi-architect": {
      "command": "fastapi-architect-mcp"
    }
  }
}

Create .mcp.json at your project root:

{
  "mcpServers": {
    "fastapi-architect": {
      "command": "/path/to/your/project/venv/bin/fastapi-architect-mcp"
    }
  }
}

Using your project's own venv gives Jedi access to all your project's dependencies, which enables full cross-file find_references and rename_symbol support.

Then restart Claude Code.

Usage examples

Once connected, you can ask Claude Code things like:

  • "List all routes in this project"

  • "What are the dependencies of the get_users handler?"

  • "Find all references to get_db across the project"

  • "Rename get_db to get_session everywhere"

  • "Inspect the UserCreate model"

  • "Are there any routes missing a response_model?"

  • "Show me the full dependency graph for the users router"

  • "Are there any mismatches between my User ORM model and UserPublic schema?"

  • "Give me an overview of this FastAPI project"

  • "If I change the User model, which endpoints are affected?"

  • "Which write endpoints have no authentication?"

  • "How does POST /chat reach the chat_logs table?"

  • "Export the knowledge graph as HTML"

Supported patterns

Dependency injection

  • def handler(x=Depends(func)) — standard FastAPI

  • def handler(*, x=Depends(func)) — keyword-only args

  • @router.get("/", dependencies=[Depends(func)]) — decorator-level deps

  • SessionDep = Annotated[Session, Depends(get_db)] — Annotated aliases (modern FastAPI)

Models

  • BaseModel — Pydantic

  • SQLModel — SQLModel

  • BaseSettings — Pydantic settings

  • RootModel — Pydantic v2

  • Inherited models (e.g. class UserCreate(UserBase))

Validators

  • @validator — Pydantic v1

  • @field_validator — Pydantic v2

Known limitations

  • find_references and rename_symbol work cross-file only when the MCP is configured to use the project's own venv (Option 2 above). With a global install, they only operate on the file where the symbol is defined.

  • get_dependencies and the knowledge graph support native FastAPI Depends() / Security() only. Other DI frameworks (Dishka, dependency-injector, etc.) are not supported.

  • Auth detection in audit_graph is inferred from names (dependencies, auth headers, called functions). Middleware-based auth is not detected; pass auth_dependencies to declare custom guards.

  • Static analysis limits: routes registered dynamically, dependencies passed through variables, calls through self or injected objects, and SQL built at runtime are only partially captured.

  • export_graph_html loads vis-network from a CDN, so viewing the page requires internet access.

  • Runtime dependencies (middleware, lifespan events, startup hooks) are not visible to static analysis and won't appear in dependency trees.

  • get_completions is most useful at attribute access positions (e.g. after a .). On empty lines it returns all Python builtins.

Requirements

  • Python 3.11+

  • Claude Code (VS Code extension or CLI)

Author

Abdessamad Touzani

Available Tools

19 tools
audit_graphA

Project-wide checks: write routes without auth, duplicate routes, routers never mounted, unused schemas, unreferenced ORM models, dependency cycles and parse errors.

Auth is inferred from dependency names, auth Header params and calls to auth-like functions. Pass auth_dependencies (function names) to declare custom guards the heuristics miss.

Inputs: project_root (required), auth_dependencies.

build_dependency_graphB

Build a full dependency graph for the routes of a file: route → handler → dependencies → models.

Inputs: file (required), project_root (required). Returns: result

build_knowledge_graphA

Build or refresh the project's FastAPI knowledge graph and return its statistics.

The graph links routes, handlers, dependencies, schemas, ORM models, SQL tables, templates and function calls. It is cached in <project_root>/.fastapi-architect/ and only changed files are re-parsed, so other graph tools are fast. Use force=True to rebuild from scratch.

Inputs: project_root (required), force.

detect_schema_orm_mismatchesC

Detect field mismatches between a SQLAlchemy ORM model and a Pydantic schema.

Inputs: orm_file (required), orm_model (required), schema_file (required), schema_model (required).

export_graph_htmlA

Export the knowledge graph as a standalone interactive HTML page (open it in a browser).

Nodes are colored by type (Route, Handler, Dependency, Schema, ORMModel, Table...), with search, type filters and a details panel listing each node's connections. Defaults to <project_root>/.fastapi-architect/graph.html. Rendering loads vis-network from a CDN.

Inputs: project_root (required), output_path.

find_model_usagesC

Find all places a Pydantic model is used as a type annotation across the project.

Inputs: file (required), model (required). Returns: result

find_pathC

Shortest paths between two nodes, e.g. from a route to a table ("POST /chat" → "chat_logs").

Directed paths are tried first; if none exists, direction is ignored and directed is false.

Inputs: source (required), target (required), project_root (required), max_paths.

find_referencesB

Find all references to the symbol at the given position across the project.

Inputs: file (required), line (required), column (required). Returns: result

get_completionsC

Return completion suggestions at the given cursor position.

Inputs: file (required), line (required), column (required). Returns: result

get_dependenciesA

Get the full Depends() injection tree for a FastAPI handler across the entire project.

Includes router-level, include_router, decorator-level and signature dependencies. handler may be a function name, a "Class.method" qualname, or a graph id ("app.routes.users:list_users").

Inputs: handler (required), project_root (required).

go_to_definitionA

Return the file and line where the symbol at the given position is defined.

Inputs: file (required), line (required), column (required). Returns: result

graph_neighborsA

Explore the knowledge graph around a node.

node can be a graph id, a route ("GET /api/users/" or "/api/users/"), a table name, or a function/class name. direction is "out" (what it uses), "in" (what uses it) or "both". edge_types filters edges, e.g. ["DEPENDS_ON", "CALLS"]. Valid types: INCLUDES, HAS_ROUTE, HANDLED_BY, DEPENDS_ON, ACCEPTS, RETURNS, CALLS, USES, QUERIES, RENDERS, MIDDLEWARE, INHERITS, MAPS_TO, REFERENCES, RELATES_TO, MIRRORS, DEFINES (excluded by default).

Inputs: node (required), project_root (required), depth, direction, +1 more.

graph_reportA

A concise Markdown overview of the project: stats, routes with their auth, hubs and audit findings. Good first call to understand an unfamiliar FastAPI codebase. With save=True the report is also written to <project_root>/.fastapi-architect/GRAPH_REPORT.md.

Inputs: project_root (required), save. Returns: result

impact_analysisB

What is affected if symbol changes: routes, handlers, dependencies, schemas, ORM models...

Follows reverse edges (callers, users, dependents, subclasses, mirroring schemas, tables → models). Each impacted route includes a via chain explaining why. symbol accepts the same forms as graph_neighbors (e.g. "User", "get_db", "users" for a table, "app.models.user:User").

Inputs: symbol (required), project_root (required), max_depth.

inspect_modelB

Inspect a Pydantic model: fields with types/defaults, and validators.

Inputs: file (required), model (required).

list_modelsC

List all Pydantic BaseModel classes defined in a file.

Inputs: file (required). Returns: result

list_routesC

List all FastAPI routes across the entire project, with full paths (router prefixes applied).

Inputs: project_root (required). Returns: result

rename_symbolC

Rename the symbol at the given position across all files in the project.

Inputs: file (required), line (required), column (required), new_name (required).

validate_response_modelsC

Detect FastAPI routes missing a response_model declaration.

Inputs: file (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: model inspection vs. listing, route enumeration vs. dependency trees, graph building vs. exploration, and audit vs. reporting. Even overlapping tools like impact_analysis and graph_neighbors differ in focus (impact vs. generic navigation). No ambiguity for agent selection.

    Naming Consistency4/5

    The vast majority follow a consistent verb_noun snake_case pattern (inspect_model, list_routes, build_dependency_graph). A few like impact_analysis and graph_neighbors deviate slightly from the verb-first convention but remain predictable and readable, so only minor inconsistency.

    Tool Count4/5

    19 tools is on the heavier side (borderline per rubric), but the FastAPI architecture domain is complex and the tool set covers analysis, refactoring, audit, graph exploration, and IDE-like features. Each tool earns its place; the count feels slightly large but not excessive.

    Completeness5/5

    The surface is highly complete for its purpose: covers model inspection/listing/usages, route enumeration/dependencies/validation, graph construction/exploration/impact/pathfinding, audit checks, reporting, and common IDE operations (references, completions, go-to-definition). No obvious dead ends or missing core capabilities.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides dynamic codebase context to Claude Code through tools like hybrid search, recent changes, and symbol definitions, enhancing AI-assisted coding with local RAG.
      8
      35 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An extensible MCP server that provides intelligent Python code analysis, navigation, and understanding capabilities for AI assistants like Claude.
      22
      167 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for real-time analysis of Lovable-generated projects, enabling Claude Desktop to instantly understand project structure, components, dependencies, and more.
      39
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Instantly converts any running FastAPI application into an MCP server by parsing its OpenAPI spec, enabling Claude to call all endpoints via natural language without manual tool writing.
      -