Build a Model Context Protocol (MCP) Server in Python: Complete Step-by-Step Guide

The Model Context Protocol (MCP), pioneered by Anthropic in late 2024 and adopted across the developer ecosystem in 2025 and 2026, standardizes how Large Language Models securely access local and remote data sources, developer tools, and enterprise APIs. Before MCP, connecting an AI coding assistant (like Claude Desktop, Cursor, or an autonomous agent) to your local SQLite database, Git repository, or Kubernetes cluster required custom brittle scripts, ad-hoc JSON-RPC setups, or proprietary plugins.

In this comprehensive tutorial, we build a production-ready MCP server in Python from scratch using the official mcp SDK. We implement type-safe tools, dynamic context resources, error handling, and test the server using both the official MCP Inspector and Claude Desktop.

1. Architectural Overview & MCP Communication Lifecycle

The Model Context Protocol uses a clean client-host-server topology. The AI client acts as the host, spawning your MCP server process over standard input/output (stdio) or Server-Sent Events (SSE):

┌────────────────────────────────────────────────────────┐
│            MCP Host (Claude Desktop / Cursor)          │
└───────────────────────────┬────────────────────────────┘
                            │ Standard Input / Output (stdio)
                            ▼
┌────────────────────────────────────────────────────────┐
│             Python FastMCP Server (Your Code)          │
│  ┌──────────────────┐  ┌──────────────────┐            │
│  │  @mcp.tool()     │  │  @mcp.resource() │            │
│  │  Tool Calling    │  │  Context Data    │            │
│  └────────┬─────────┘  └────────┬─────────┘            │
└───────────┼─────────────────────┼──────────────────────┘
            │                     │
            ▼                     ▼
┌───────────────────────┐   ┌───────────────────────────┐
│ Local SQLite / Files  │   │ Cloud APIs / Observability│
└───────────────────────┘   └───────────────────────────┘

The protocol supports three primary primitives:
1. Tools: Executable functions callable by the model (e.g. executing a SQL query, analyzing a git diff).
2. Resources: Read-only data payloads that provide background context to the model (e.g. system specs, database schemas).
3. Prompts: Pre-engineered prompt templates that users can trigger inside their AI interface.

2. Prerequisites & Environment Setup

Ensure your local machine has Python 3.10+ installed. Create an isolated virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]>=1.3.0" pydantic>=2.7.0 psutil>=5.9.0 aiosqlite>=0.20.0

💡 Developer Note: The mcp[cli] package bundles both the core MCP transport library and the developer testing CLI.

3. Step-by-Step Implementation: Building a Production FastMCP Server

We will implement a server that exposes two enterprise capabilities:
1. System Health Inspector: Returns real-time CPU, RAM, and disk utilization.
2. Safe SQLite Query Runner: Allows the AI to query read-only SQLite databases without risking unauthorized data mutations (DROP, DELETE).

Create mcp_server.py:

import os
import sqlite3
import psutil
from typing import Dict, Any, List
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

# Initialize FastMCP Server
mcp = FastMCP("TechJunkGigs-DevServer")

class QueryInput(BaseModel):
    query: str = Field(..., description="SQL SELECT query to execute on the local database")
    db_path: str = Field(default="analytics.db", description="Relative or absolute path to SQLite database")

@mcp.resource("system://metrics")
def get_system_metrics() -> str:
    # Provides current host CPU, RAM, and disk telemetry to the model context.
    cpu_pct = psutil.cpu_percent(interval=0.5)
    mem = psutil.virtual_memory()
    disk = psutil.disk_usage('/')

    return (
        f"Host Telemetry Report:
"
        f"- CPU Utilization: {cpu_pct}%
"
        f"- Memory Used: {mem.percent}% ({mem.used // (1024**2)}MB / {mem.total // (1024**2)}MB)
"
        f"- Disk Space: {disk.percent}% used ({disk.free // (1024**3)}GB free)
"
    )

@mcp.tool()
def execute_safe_query(params: QueryInput) -> List[Dict[str, Any]]:
    # Executes a strictly read-only SQL query against a local SQLite database.
    clean_query = params.query.strip()

    # Enforce Read-Only Guardrails
    disallowed = ["DROP", "DELETE", "UPDATE", "INSERT", "ALTER", "TRUNCATE", "REPLACE"]
    first_token = clean_query.split()[0].upper() if clean_query else ""

    if first_token != "SELECT" or any(kw in clean_query.upper() for kw in disallowed):
        raise ValueError(f"Security Violation: Only SELECT queries are permitted. Found: {clean_query}")

    if not os.path.exists(params.db_path):
        raise FileNotFoundError(f"Database file not found at: {params.db_path}")

    conn = sqlite3.connect(params.db_path)
    conn.row_factory = sqlite3.Row
    try:
        cursor = conn.cursor()
        cursor.execute(clean_query)
        rows = cursor.fetchall()
        return [dict(row) for row in rows]
    finally:
        conn.close()

if __name__ == "__main__":
    # Runs over standard input/output (stdio) for local AI clients
    mcp.run(transport="stdio")

4. Testing with the MCP Inspector

Before connecting to Claude Desktop or an autonomous agent, test your server interactively using the official web-based MCP Inspector:

npx @modelcontextprotocol/inspector python mcp_server.py

The inspector launches a local dashboard at http://localhost:5173. You can list tools, inspect the generated JSON Schema for execute_safe_query, and trigger test inputs to verify error responses.

5. Integrating with Claude Desktop & Cursor

To enable this server in Claude Desktop, open your Claude configuration file:
– macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
– Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your server definition under mcpServers:

{
  "mcpServers": {
    "techjunkgigs-server": {
      "command": "/Users/your_user/techjunkgigs/.venv/bin/python",
      "args": ["/Users/your_user/techjunkgigs/mcp_server.py"]
    }
  }
}

Restart Claude Desktop. Look for the hammer (🛠️) icon in the bottom right corner of Claude’s prompt bar. Claude now has native access to execute queries and read your system metrics!

6. Common Errors & Troubleshooting

7. Performance & Production Recommendations

1. Keep stdout Clean: Any message sent to standard out that is not valid JSON-RPC 2.0 will immediately crash the client. Configure standard logging to output to sys.stderr.
2. Enforce Strict Input Validation: Use Pydantic fields with explicit descriptions. LLMs read the field descriptions to deduce valid parameter ranges.
3. Transition to SSE for Remote Deployments: For cloud deployments (e.g. running your MCP server on a DigitalOcean droplet or AWS EC2), switch from transport="stdio" to transport="sse".

8. Frequently Asked Questions (FAQ)

What is the difference between an MCP Server and a standard REST API?

A REST API exposes HTTP endpoints meant for deterministic web clients. An MCP server advertises machine-readable tool schemas, context resources, and error codes directly into the LLM’s system prompt loop, allowing the model to autonomously decide when and how to call them.

Can I write MCP servers in languages other than Python?

Yes. Official MCP SDKs exist for TypeScript/Node.js, Python, Kotlin, and Go.

Is MCP safe to use with sensitive data?

MCP operates with strict local privilege separation. The AI model never receives your raw credentials; it only triggers designated functions whose code you control.

9. Summary & Next Steps

You now have a fully functional Model Context Protocol server in Python. You can expand this foundation to connect Git repositories, local vector stores, or Docker daemons. For next steps, explore our guide on tool calling workflows in autonomous agents.