# jlowin/fastmcp architecture

> Architecture diagram of the GitHub repository jlowin/fastmcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlowin/fastmcp
- Repository: https://github.com/jlowin/fastmcp

## Overview

##### Project type and overall purpose
- FastMCP is an open-source Python framework/SDK for building Model Context Protocol (MCP) servers and clients.
- It provides a CLI (`fastmcp`) to bootstrap projects, install integrations, and run servers.
- Key internal modules: `fastmcp.cli`, `fastmcp.client`, `fastmcp.server`, plus `utilities`, `tools`, `resources`, and `prompts`.

##### File structure with a focus on the CLI
- `src/fastmcp/cli/` contains the CLI entrypoints and subcommands:
- `cli.py` – core argument parsing and dispatcher
- `run.py` – “fastmcp run” command (bootstraps and launches a server)
- `install/` – “fastmcp install” integrations (claude_code, claude_desktop, cursor, mcp_json)
- `claude.py` – utility for Claude-specific subcommands
- The CLI commands invoke:
- Core library (`fastmcp.server` to start HTTP/SSE or STDIO)
- Client library (`fastmcp.client`) for testing or in-memory transports
- Configuration management (`fastmcp.mcp_config`, `fastmcp.settings`)
- External dependencies (pip via UV, environment variables)

##### README for CLI-related insights
- Usage examples:
- `fastmcp run server.py --transport http --host 0.0.0.0 --port 8000`
- `fastmcp install claude-code`
- It describes three built-in transports and multiple subcommands.

##### Main components
A. User Shell
B. fastmcp CLI (`src/fastmcp/cli/cli.py`)
C. Subcommand Handlers
1. Run Handler (`run.py`)
2. Install Handlers (`install/*.py`)
3. Integration Helpers (`claude.py`)
D. Core Library Modules
1. Server (`fastmcp.server.*`)
2. Client (`fastmcp.client.*`)
3. Config & Settings (`fastmcp.mcp_config`, `fastmcp.settings`)
E. External Tools & Services
1. Python Interpreter & pip (via UV)
2. Network (HTTP, SSE)
3. File System (user’s code, config files)

##### Architectural patterns & principles
- **Command Pattern**: each CLI subcommand is a distinct handler class/function
- **Dependency Injection**: subcommands import and use core modules (`server`, `client`, `utilities`)
- **Plugin/Extension Points**: install subcommands allow external integrations to hook into the framework
- **Separation of Concerns**: CLI layer solely handles I/O & orchestration, delegating business logic to library modules

##### Detailed component list
- User Shell
- fastmcp CLI Entrypoint
- Argument Parser
- Command Registry
- Subcommands (grouped):
1. run.py
2. install/
– claude_code
– claude_desktop
– cursor
– mcp_json
3. claude.py
- Core Library
- fastmcp.server (transport modules: stdio, http, sse)
- fastmcp.client (transports, testing)
- fastmcp.mcp_config + fastmcp.settings
- External Services
- Python/pip (via UV)
- Network endpoints (if HTTP/SSE)
- File system (server.py, config files)

[BLUE] User Shell
↓ “fastmcp install claude-code”
[BLUE] CLI Parser → Command Registry
↳ “install” command → [BLUE] Install Handler (install/claude_code.py)
↔ [GRAY] pip/UV (executes `pip install anthropic-sdk`)
↔ [GREEN] fastmcp.mcp_config (updates config)
↳ “run” command → [BLUE] Run Handler (run.py)
→ [GRAY] FileSystem (reads server.py)
→ [GREEN] fastmcp.server (mcp.run())
→ [GRAY] Network (HTTP/SSE sockets)
↳ “claude” command → [BLUE] claude.py helper
↔ [GREEN] fastmcp.client.auth

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        UserShell["User Shell"]:::external
        CLIEntrypoint["fastmcp CLI Entrypoint\n(cli.py)"]:::cli
        CLIParser["Argument Parser & Dispatcher"]:::cli
        subgraph "Subcommands"
            direction TB
            RunHandler["Run Handler\n(run.py)"]:::cli
            subgraph "Install Handlers"
                direction TB
                ClaudeCode["claude_code Installer"]:::cli
                ClaudeDesktop["claude_desktop Installer"]:::cli
                CursorInst["cursor Installer"]:::cli
                MCPJson["mcp_json Installer"]:::cli
                SharedInstall["Shared Install Utils"]:::cli
            end
            ClaudeHelper["Integration Helper\n(claude.py)"]:::cli
        end
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        subgraph "Server Modules"
            direction TB
            ServerCore["Server Entrypoint\n(server.py)"]:::core
            HTTP["HTTP Transport\n(http.py)"]:::core
            SSE["SSE Transport\n(low_level.py)"]:::core
            Context["Context & Dependencies\n(context.py, dependencies.py)"]:::core
            OpenAPI["OpenAPI Support\n(openapi.py)"]:::core
            Proxy["Proxy Server\n(proxy.py)"]:::core
            AuthCore["Auth Plugins\n(auth/auth.py)"]:::core
            Middleware["Middleware Components"]:::core
        end
        subgraph "Client Modules"
            direction TB
            ClientCore["Client API\n(client.py)"]:::core
            Transports["Test Transports\n(transports.py)"]:::core
            AuthClient["Client Auth\n(auth/bearer.py, oauth.py)"]:::core
        end
        subgraph "Config & Settings"
            direction TB
            MCPConfig["MCP Config Manager\n(mcp_config.py)"]:::core
            Settings["Global Settings\n(settings.py)"]:::core
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PipUV["Python/pip (via UV)"]:::external
        FileSystem["File System"]:::external
        Network["Network (HTTP/SSE)"]:::external
    end

    %% Connections
    UserShell -->|"fastmcp <command>"| CLIEntrypoint
    CLIEntrypoint -->|"parse_args() / dispatch()"| CLIParser
    CLIParser -->|"dispatch run"| RunHandler
    CLIParser -->|"dispatch install"| ClaudeCode
    CLIParser -->|"dispatch install"| ClaudeDesktop
    CLIParser -->|"dispatch install"| CursorInst
    CLIParser -->|"dispatch install"| MCPJson
    CLIParser -->|"dispatch install"| SharedInstall
    CLIParser -->|"dispatch claude"| ClaudeHelper

    RunHandler -->|"reads script"| FileSystem
    RunHandler -->|"mcp.run()"| ServerCore
    RunHandler -->|"opens sockets"| Network

    ClaudeCode -->|"executes pip install"| PipUV
    ClaudeDesktop -->|"executes pip install"| PipUV
    CursorInst -->|"executes pip install"| PipUV
    MCPJson -->|"executes pip install"| PipUV
    SharedInstall -->|"updates config"| MCPConfig

    ClaudeHelper -->|"uses client auth"| AuthClient

    ServerCore -->|"uses modules"| HTTP
    ServerCore -->|"uses modules"| SSE
    ServerCore -->|"uses modules"| Context
    ServerCore -->|"uses plugins"| AuthCore
    ServerCore -->|"provides API"| OpenAPI
    ServerCore -->|"proxies"| Proxy
    ServerCore -->|"applies"| Middleware

    ClientCore -->|"offers API"| Transports

    %% Click Events
    click CLIEntrypoint "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/cli.py"
    click RunHandler "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/run.py"
    click ClaudeCode "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/install/claude_code.py"
    click ClaudeDesktop "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/install/claude_desktop.py"
    click CursorInst "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py"
    click MCPJson "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/install/mcp_json.py"
    click SharedInstall "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/install/shared.py"
    click ClaudeHelper "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/claude.py"
    click ServerCore "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py"
    click HTTP "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/http.py"
    click SSE "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/low_level.py"
    click Context "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py"
    click AuthCore "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/auth.py"
    click ClientCore "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py"
    click Transports "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py"
    click MCPConfig "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/mcp_config.py"
    click Settings "https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/settings.py"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
