What can you do with this server?

mcp-architect is an MCP server that gives AI assistants a structured, local, and private architectural understanding of any codebase — no API keys, network calls, or external models required. * architecture_overview – Get a high-level map of a repository: detected languages, frameworks, file count, lines of code, top-level structure, and entry points. The best starting point for understanding an unfamiliar codebase. * dependency_graph – Analyze how internal modules import each other, identify the most-depended-upon architectural hub modules, and detect circular dependencies. Supports Python and JavaScript/TypeScript with auto-detection. * hotspots – Find files most deserving attention based on size, complexity, git change frequency, or combined risk score (configurable, default top 10 per category). * explain – Deep-dive into a specific folder or file: lists its sub-files, public classes/functions, and external dependencies. * Impact analysis – Determine what breaks if a specific component changes, including direct importers, transitive blast radius, and hub risk. Runs entirely locally using Python's standard library (ast, os, re), with no heavy dependencies. Compatible with Claude Desktop, Cursor, Windsurf, Cline, and any MCP client.

How do I use mcp-architect?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-architect Give me an architecture overview, dependency graph, and hotspots for ~/code/my-app." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-architect

by kannajune

Overview Schema Source Related Servers Discussions Admin

Python

Local

🏛️ mcp-architect

Stop pasting your file tree into Claude. Give any AI assistant real architectural understanding of a codebase — local, private, zero‑config.

PyPI License: MIT Python 3.10+ MCP

AI coding assistants are great at files but blind to architecture. Every session you re‑explain the structure, paste the file tree, and hope it guesses your module boundaries right. mcp-architect is an MCP server that hands your assistant a structured map of any codebase — tech stack, dependency graph, hotspots, and module summaries — computed 100% locally with no API keys and no model required.

It works with Claude Desktop, Cursor, Windsurf, Cline, or any MCP client.

Why

Without mcp-architect	With mcp-architect
"Here's my file tree, please figure out the structure…"	`architecture_overview` → stack, entry points, structure in one call
AI guesses how modules relate	`dependency_graph` → real import graph + circular‑dependency detection
"Which files matter?"	`hotspots` → largest, most complex, most‑changed, highest‑risk
Re‑explaining a package every time	`explain` → classes, functions, and deps of any folder

Everything runs on your machine. Your code never leaves it.

Related MCP server: Code-Index-MCP

Quickstart

Install

pip install mcp-architect

…or skip the install entirely and let your MCP client fetch it on demand with uvx (shown below).

1. Add it to your MCP client

Claude Desktop — edit claude_desktop_config.json:

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

Prefer pip? pip install mcp-architect. Or run the latest straight from source:
{ "mcpServers": { "architect": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/kannajune/mcp-architect", "mcp-architect"]
} } }

Restart your client. That's it — no keys, no model download.

2. Ask your assistant

"Use the architect tools to give me an overview of ~/code/my-app, then show me its dependency graph and the highest‑risk files."

What you get

# Architecture Overview — my-app

**151 files · 17,368 lines of code**

## Languages
- **Python** — 93 files, 13,683 LOC
- **TypeScript** — 23 files, 3,120 LOC

## Frameworks / key libraries
- FastAPI
- React
- Tailwind CSS

## Entry points
- main.py

# Dependency Graph — my-app

**118 modules · 172 internal import edges**

## Most depended-upon (architectural hubs)
- `app.signals.signal_parser` — imported by 12 modules
- `app.core.integrations_registry` — imported by 11 modules

## Circular dependencies
✅ no circular dependencies found

Tools

Tool	What it tells the AI
`architecture_overview`	Languages, frameworks, ecosystems, size, top‑level structure, entry points
`dependency_graph`	Internal import graph, architectural hubs, circular dependencies
`impact_analysis`	What breaks if you change X — direct importers + transitive blast radius, hub risk
`hotspots`	Largest / most complex / most‑changed (git) / highest‑risk files
`explain`	Deep‑dive a folder or file: classes, functions, external deps

Design principles

Zero heavy dependencies. Pure Python standard library for all analysis (ast, os, re). The only runtime dep is the MCP SDK itself. Installs in seconds.
Local & private. No network calls, no telemetry, no LLM. Your source never leaves your machine.
Language‑aware. Full AST parsing for Python; import parsing for JavaScript/TypeScript; file/LOC stats for 25+ languages.
Decoupled core. The analysis layer (mcp_architect.analysis) is importable and testable on its own — use it as a plain Python library too.

from mcp_architect.analysis import get_overview, get_dependency_graph
print(get_overview("~/code/my-app")["frameworks"])

The dependency and complexity analysis is heuristic — designed to give an AI useful, fast situational awareness, not to replace a full static analyzer.

Pin to one project (optional)

Set MCP_ARCHITECT_ROOT so tools default to a fixed repo and you can omit paths:

{ "mcpServers": { "architect": {
    "command": "uvx", "args": ["mcp-architect"],
    "env": { "MCP_ARCHITECT_ROOT": "/Users/you/code/my-app" }
} } }

How it compares

mcp-architect isn't a semantic search engine or a context packer — it's a structural lens any AI assistant can call on demand. It's designed to complement the tools below, not replace them:

Tool / approach	Great at	What mcp-architect adds
Cursor codebase indexing	Semantic snippet retrieval, inside Cursor	Works in any MCP client (Claude Desktop, Cline, Windsurf, Cursor…), 100% local (no cloud embeddings), and returns architecture — dependency graph, cycles, hotspots — not just relevant snippets
Serena (LSP-based code agent)	Precise symbol-level navigation & edits	Zero-config, zero heavy deps (stdlib — no language servers to install) and a high-level architectural map instead of symbol-by-symbol operations
RepoPrompt (context packing)	Hand-picking files into a prompt	The assistant pulls structured architecture on demand via tools — no manual file selection, no token-budget juggling

In one line: Cursor and Serena help the AI read your code; mcp-architect helps it understand the architecture — locally, in any client. They stack well together.

Roadmap

Layered‑architecture / boundary‑violation detection
Go, Rust & Java import graphs
Optional local‑LLM (Ollama) narrative summaries
compare tool for before/after architecture diffs

Contributions welcome — see CONTRIBUTING.

Contributing

PRs and issues welcome! Run the tests with:

pip install -e ".[dev]"
pytest

License

MIT © Kannan Dharmalingam

Available Tools

5 tools

architecture_overviewA

High-level map of a codebase: languages, frameworks, size, structure, and entry points. Start here to understand an unfamiliar repo.

Args: path: Repo path to analyze. Relative to the server's working directory (or MCP_ARCHITECT_ROOT if set). Defaults to the whole project.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It explains the path parameter behavior and defaults but does not disclose side effects, permissions, or safety (e.g., read-only nature). It adequately describes what the tool does but lacks explicit behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a clear front-loaded purpose statement followed by an args section. Every sentence adds value with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single optional parameter and the presence of an output schema, the description is complete. It covers what the tool does, how to use it, and relevant path behaviors. No additional context is needed for effective invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for the single parameter, but the description provides clear semantics: 'Repo path to analyze. Relative to the server's working directory (or MCP_ARCHITECT_ROOT if set). Defaults to the whole project.' This adds meaning beyond the schema's type and default fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool provides a 'high-level map of a codebase' including 'languages, frameworks, size, structure, and entry points.' It also suggests starting here for unfamiliar repos, which clearly differentiates it from sibling tools like dependency_graph, explain, and hotspots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to 'Start here to understand an unfamiliar repo,' giving clear contextual guidance. It does not explicitly list exclusions or when not to use, but the context is sufficient for an agent to infer appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

dependency_graphA

Map how internal modules import each other, the most-depended-upon modules, and any circular dependencies. Use to understand coupling.

Args: path: Repo path to analyze. language: 'auto', 'python', or 'js'/'ts'.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		.
`language`	No		auto

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear the burden of disclosing behavioral traits. It fails to mention whether the tool reads-only or modifies the repo, any permission requirements, or performance implications. The purpose is clear but operational context is missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short sentences and a parameter list. It is front-loaded with the core action and avoids unnecessary words. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and the presence of an output schema (not shown but indicated), the description adequately covers purpose and parameters. It could mention repository structure prerequisites (e.g., git repo) or behavior for unsupported languages, but overall it is sufficiently complete for an agent to use the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the parameter explanations in the description are essential. They clarify 'path' as the repo path and 'language' as an auto-detection option with supported languages. This adds basic value, but could be more detailed (e.g., whether path must be a directory or file).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool maps internal module imports, identifies most-depended-upon modules, and finds circular dependencies. It distinguishes from siblings like architecture_overview (high-level structure) and hotspots (complexity analysis) by focusing specifically on dependency relationships.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests using the tool to understand coupling, providing a clear use case. However, it does not specify when to avoid it or mention alternatives among siblings, leaving the agent to infer usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explainA

Deep-dive a single folder or file: its files, public classes/functions, and external dependencies.

Args: path: Repo root. module: Sub-path within the repo (folder or file) to explain.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		.
`module`	No		.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. It clearly states the tool returns files, classes/functions, and dependencies. However, it does not mention whether the tool is read-only, requires permissions, or has any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus concise Args list. Front-loaded with the main purpose. No extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return value details are not needed. The description covers the core functionality. Could mention complementarity with siblings or scalability notes, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds minimal context: 'Reposit root' for path and 'Sub-path... to explain' for module. The defaults are noted in schema but no additional format or usage details are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool performs a 'deep-dive' into a single folder or file, listing files, public classes/functions, and external dependencies. This distinguishes it from siblings like architecture_overview (high-level) and dependency_graph (dependencies only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. The description implies it's for detailed analysis of a single module, but does not compare with siblings or mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hotspotsA

Find the files most worth attention: largest, most complex, most frequently changed (git), and highest combined risk.

Args: path: Repo path to analyze. top: How many files per category (default 10).

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		.
`top`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose whether the tool is read-only, safe to run, or any side effects. The behavior is implied to be analytical but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences for purpose and a compact args list. Information is front-loaded and every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two optional parameters and an output schema (not shown), the description is sufficient for basic understanding. However, it does not cover edge cases or prerequisites, but is adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds basic meaning for both parameters (path as repo path, top as count per category with default). This compensates partially, but lacks details like units or accepted formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds 'files most worth attention' and lists specific criteria (largest, most complex, most frequently changed, highest risk). It distinguishes itself from sibling tools like architecture_overview, dependency_graph, and explain by focusing on file-level analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to identify important files, but does not explicitly mention when not to use or compare with alternatives. Sibling tools are present but not referenced.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

impact_analysisA

What could break if you change target? Walks the import graph backwards to list direct importers and the full transitive blast radius, and flags whether the target is a high-risk hub. Use before editing/refactoring a module.

Args: target: Module or file to analyze, e.g. "app/core/db.py" or "app.core.db". If omitted, returns the highest-impact modules to pick from. path: Repo root. language: 'auto', 'python', or 'js'/'ts'.

ParametersJSON Schema

Name	Required	Default
`target`	No
`path`	No	.
`language`	No	auto

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description fully discloses behavior: walks import graph backwards, lists direct and transitive importers, flags high-risk hubs. However, does not mention potential performance implications for large graphs or that it is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is very concise and well-structured. Opens with a question to engage, then explains functionality, usage recommendation, and parameter details. Every sentence is meaningful with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that output schema exists (not shown but context indicates true), description covers inputs and behavior adequately. With 3 optional parameters and no annotations, it explains the tool's purpose and inputs well. Could mention that it is read-only or safe to run.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds significant value. It explains each parameter: target (module/file, default returns highest-impact modules), path (repo root), language (auto, python, js/ts). Provides examples and clarifies behavior when omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it walks import graph backwards to list importers and blast radius, and flags high-risk hubs. It is specific about the action (impact analysis) and resource (target module). Distinguishes from sibling tools like dependency_graph by focusing on backward analysis and change impact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use before editing/refactoring a module.' Also mentions that omitting target returns highest-impact modules. Provides clear context but does not explicitly contrast with sibling tools or state when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

1 tool updatev1.0.2Jun 18, 2026
- Changedimpact_analysis2 fields changed
  - addedInput schema / properties / target / default
```
Added value: +""
```
  - removedInput schema / required
```
Removed value: -[
-  "target"
-]
```
1 tool updatev1.0.1Jun 18, 2026
- Addedimpact_analysis
4 tool updatesv1.0.0Jun 18, 2026
- First observedarchitecture_overview
- First observeddependency_graph
- First observedexplain
- First observedhotspots

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-06-18 16:45 across 5 tools

Disambiguation5/5

Each tool targets a distinct aspect of code analysis: high-level overview, dependency mapping, deep-dive explanation, complexity hotspots, and impact analysis. There is no overlap in purpose.

Naming Consistency4/5

Four tools use descriptive noun phrases (architecture_overview, dependency_graph, hotspots, impact_analysis), but 'explain' is a single verb, breaking the pattern. The naming is still clear and mostly consistent.

Tool Count5/5

Five tools cover the essential code analysis tasks without being excessive or insufficient. The set is well-scoped for a codebase exploration and refactoring server.

Completeness5/5

The tools cover the main analysis needs: high-level orientation, dependency understanding, detailed module explanation, risk identification, and change impact. No obvious gaps for the intended use cases.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Mapnostics
io.github.ffteema
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code Analysis Developer Tools
1
Umtri
io.umtri
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code Analysis Knowledge & Memory Software Architecture
1
TeamShared B
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
1331
ArchGraphOAuth
dev.archgraph
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code Analysis Software Architecture Developer Tools
2

Related MCP Servers

Serena
Coding Agents Developer Tools Code Analysis
chrisgreenx-ctrl
A
license
A
quality
D
maintenance
A coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases at the symbol level rather than working with entire files.
Updated 8 months ago (2026-01-05 21:07 UTC)
29
MIT
Code-Index-MCP
Developer Tools Code Analysis Search
Consiliency
A
license
Not graded
quality
A
maintenance
Local-first code indexer that provides deep code understanding for Claude and other LLMs with symbol/text search across 48+ languages, semantic search capabilities, and real-time index updates through the Model Context Protocol.
Updated 2 days ago (2026-09-12 10:36 UTC)
57
MIT
Octocode
RAG Systems Code Analysis Knowledge & Memory
Muvon
A
license
Not graded
quality
A
maintenance
Semantic code indexer with GraphRAG knowledge graph. Index your codebase, search in natural language, and expose everything via MCP so AI agents understand architecture — not just files.
Updated 3 days ago (2026-09-11 05:28 UTC)
471
Apache 2.0
Carto MCP Server
Code Analysis Developer Tools Documentation Access
theanshsonkar
A
license
Not graded
quality
B
maintenance
Enables AI coding tools to query your live codebase for routes, import graph, domain context, and blast radius, eliminating hallucinations about project structure.
Updated 14 days ago (2026-08-31 05:02 UTC)
377 npm
76
MIT