FastAPI Architect MCP
An MCP server that gives Claude Code IDE-level intelligence for FastAPI projects using semantic code navigation, safe refactoring, route/dependency inspection, Pydantic model analysis, and a static knowledge graph.
Find all references to a symbol across the project
Safely rename symbols across all files
Jump to definitions and get completions at a cursor position
List FastAPI routes with full paths and router prefixes
Get full
Depends()injection trees for handlersList and inspect Pydantic/SQLModel models: fields, types, defaults, validators
Find everywhere a model is used across the project
Detect routes missing
response_modeland schema/ORM field mismatchesBuild and refresh a typed knowledge graph of the app
Generate markdown graph reports, explore neighbors, and run impact analysis
Find shortest paths between nodes (e.g. route → SQL table)
Audit routes for missing auth, duplicates, unused schemas, and dependency cycles
Export the graph as a standalone interactive HTML visualization
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 all usages of a symbol across the project |
| Safely rename a symbol across all files |
| Jump to where a symbol is defined |
| Get completion suggestions at a cursor position |
| List all FastAPI routes with their full paths (router prefixes applied) |
| Get the full injection tree for a handler (router, decorator and signature |
| Per-file view: route → input models → dependencies → response model |
| Detect routes missing a |
| List all Pydantic/SQLModel models in a file |
| Inspect a model's fields, types, defaults, and validators |
| Find everywhere a model is used across the project |
| Detect field mismatches between ORM model and Pydantic schema |
Knowledge graph
Tool | Description |
| Build or refresh the project graph and return its statistics |
| Markdown overview: routes with their auth, most connected symbols, tables, audit findings |
| Explore what a route, function, model or table uses and is used by |
| Everything affected if a symbol changes, with the chain explaining each impacted route |
| Shortest paths between two nodes, e.g. from a route to a SQL table |
| Write routes without auth, duplicate or unmounted routes, unused schemas, unreferenced ORM models, dependency cycles |
| 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-mcpConfiguration
Option 1 — Global (available in all projects)
Add to ~/.claude/settings.json:
{
"mcpServers": {
"fastapi-architect": {
"command": "fastapi-architect-mcp"
}
}
}Option 2 — Per project (recommended for best results)
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_usershandler?""Find all references to
get_dbacross the project""Rename
get_dbtoget_sessioneverywhere""Inspect the
UserCreatemodel""Are there any routes missing a response_model?"
"Show me the full dependency graph for the users router"
"Are there any mismatches between my
UserORM model andUserPublicschema?""Give me an overview of this FastAPI project"
"If I change the
Usermodel, which endpoints are affected?""Which write endpoints have no authentication?"
"How does
POST /chatreach thechat_logstable?""Export the knowledge graph as HTML"
Supported patterns
Dependency injection
def handler(x=Depends(func))— standard FastAPIdef handler(*, x=Depends(func))— keyword-only args@router.get("/", dependencies=[Depends(func)])— decorator-level depsSessionDep = Annotated[Session, Depends(get_db)]— Annotated aliases (modern FastAPI)
Models
BaseModel— PydanticSQLModel— SQLModelBaseSettings— Pydantic settingsRootModel— Pydantic v2Inherited models (e.g.
class UserCreate(UserBase))
Validators
@validator— Pydantic v1@field_validator— Pydantic v2
Known limitations
find_referencesandrename_symbolwork 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_dependenciesand the knowledge graph support native FastAPIDepends()/Security()only. Other DI frameworks (Dishka, dependency-injector, etc.) are not supported.Auth detection in
audit_graphis inferred from names (dependencies, auth headers, called functions). Middleware-based auth is not detected; passauth_dependenciesto declare custom guards.Static analysis limits: routes registered dynamically, dependencies passed through variables, calls through
selfor injected objects, and SQL built at runtime are only partially captured.export_graph_htmlloads 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_completionsis 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
GitHub: @AbdessamadTzn
LinkedIn: abdessamadtouzani
Available Tools
19 toolsaudit_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.835 PyPIMIT
- AlicenseAqualityBmaintenanceAn extensible MCP server that provides intelligent Python code analysis, navigation, and understanding capabilities for AI assistants like Claude.22167 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for real-time analysis of Lovable-generated projects, enabling Claude Desktop to instantly understand project structure, components, dependencies, and more.39MIT
- FlicenseNot gradedqualityDmaintenanceInstantly 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.-