Topos — Claude Code MCP server: code structure analysis
Topos examines code complexity, coupling, and risky data flows, then gives an agent a concrete structural issue to investigate and improve.
claude mcp add topos -- uvx topos-mcpWhat Topos does
Topos analyzes program structure and points an agent toward a specific area to improve. Its checks cover complexity, coupling, risky data flows, and how difficult the code is for an agent to reason about. Run the evaluation again after edits to review the result.
The server supports Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, and Gemini CLI. For Claude Code, setup uses uvx topos-mcp. The CLI detects Python, Rust, JavaScript, TypeScript, C++, and Go projects; --language narrows an evaluation. Topos checks structure rather than test behavior, so it does not replace running the project’s tests.
What it helps with
- locate a repository’s most serious structural issue
- identify excessive code complexity and coupling
- inspect risky data flows
- reassess code structure after a refactor
Example prompts for the agent
- Find the main structural issue in this repository and suggest one focused change.
- Check the code for complexity and coupling, then point out the problem areas.
- Evaluate the structure again after my edits and compare the result.
How to install Topos
Platform CLI
claude mcp add topos -- uvx topos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from topos-mcp <command>
Platform CLI
codex mcp add topos -- uvx topos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from topos-mcp <command>
Config file
{
"mcpServers": {
"topos": {
"command": "uvx",
"args": [
"topos-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from topos-mcp <command>
Config file
{
"servers": {
"topos": {
"type": "stdio",
"command": "uvx",
"args": [
"topos-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from topos-mcp <command>
Platform CLI
gemini mcp add topos uvx topos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from topos-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Topos
How do I install Topos in Claude Code?
Run claude mcp add topos -- uvx topos-mcp, then restart Claude Code.
What does Topos do?
It evaluates code structure, identifies problem areas, and gives the agent a specific improvement target.
Which languages does the Topos CLI detect?
It detects Python, Rust, JavaScript, TypeScript, C++, and Go. Use --language to limit the evaluation to a selected language.
