How to Build a Custom MCP Server for Claude Code: Step-by-Step Guide

┌─────────────┐     stdio/HTTP      ┌──────────────┐
│  Claude Code │ ◄──────────────────► │  Your MCP     │
│  (Client)    │   JSON-RPC 2.0      │  Server       │
└─────────────┘                      └──────┬───────┘
                                            │
                                     ┌──────▼───────┐
                                     │  Your Tools   │
                                     │  (Python fns) │
                                     └──────────────┘

mkdir my-mcp-server && cd my-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install mcp httpx

# !/usr/bin/env python3
"""Custom MCP Server with three tools: weather, file-summary, todo-manager."""

import json
import os
from datetime import datetime
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationCapabilities
from mcp.server.stdio import stdio_server

# In-memory todo store (for demo; use SQLite in production)
todos = []
next_id = 1

server = Server("my-tools-server")

# ── Tool 1: Weather Lookup ──────────────────────────────────
@server.list_tools()
async def list_tools() -> list:
    return [
        {
            "name": "get_weather",
            "description": "Get current weather for a city. Returns temperature, conditions, and humidity.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'San Francisco' or 'Tokyo'"
                    },
                    "units": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit (default: celsius)"
                    }
                },
                "required": ["city"]
            }
        },
        {
            "name": "summarize_file",
            "description": "Summarize a text file's content — returns line count, word count, and first 500 characters.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "filepath": {
                        "type": "string",
                        "description": "Absolute path to the file to summarize"
                    }
                },
                "required": ["filepath"]
            }
        },
        {
            "name": "todo_manager",
            "description": "Manage a simple todo list. Supports 'add', 'list', 'done', and 'clear' actions.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "action": {
                        "type": "string",
                        "enum": ["add", "list", "done", "clear"],
                        "description": "Action to perform on the todo list"
                    },
                    "text": {
                        "type": "string",
                        "description": "Todo item text (required for 'add' action)"
                    },
                    "id": {
                        "type": "integer",
                        "description": "Todo ID to mark as done (required for 'done' action)"
                    }
                },
                "required": ["action"]
            }
        }
    ]

# ── Tool Execution ──────────────────────────────────────────
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list:
    global todos, next_id

    if name == "get_weather":
        city = arguments["city"]
        units = arguments.get("units", "celsius")

# Simulated weather data (replace with real API call)
        weather_data = {
            "San Francisco": {"temp": 18, "condition": "Foggy", "humidity": 82},
            "Tokyo": {"temp": 28, "condition": "Clear", "humidity": 65},
            "London": {"temp": 15, "condition": "Rainy", "humidity": 78},
            "New York": {"temp": 24, "condition": "Partly Cloudy", "humidity": 55},
        }
        data = weather_data.get(city, {"temp": 22, "condition": "Unknown", "humidity": 60})
        return [{
            "type": "text",
            "text": f"📍 {city}: {data['temp']}°{'C' if units == 'celsius' else 'F'}, {data['condition']}, Humidity: {data['humidity']}%"
        }]

    elif name == "summarize_file":
        filepath = arguments["filepath"]
        if not os.path.exists(filepath):
            return [{"type": "text", "text": f"❌ File not found: {filepath}"}]
        if not os.path.isfile(filepath):
            return [{"type": "text", "text": f"❌ Not a file: {filepath}"}]
        try:
            with open(filepath, "r") as f:
                content = f.read()
            lines = content.split("\n")
            words = content.split()
            preview = content[:500]
            return [{
                "type": "text",
                "text": f"📄 {os.path.basename(filepath)}\nLines: {len(lines)}\nWords: {len(words)}\nChars: {len(content)}\n\n--- Preview (first 500 chars) ---\n{preview}"
            }]
        except Exception as e:
            return [{"type": "text", "text": f"❌ Error reading file: {str(e)}"}]

    elif name == "todo_manager":
        action = arguments["action"]
        if action == "add":
            text = arguments.get("text", "")
            if not text:
                return [{"type": "text", "text": "❌ 'text' is required for add action"}]
            todos.append({"id": next_id, "text": text, "done": False, "created": datetime.now().isoformat()})
            next_id += 1
            return [{"type": "text", "text": f"✅ Added todo #{next_id-1}: {text}"}]
        elif action == "list":
            if not todos:
                return [{"type": "text", "text": "📋 No todos yet."}]
            lines = ["📋 Todo List:"]
            for t in todos:
                status = "✅" if t["done"] else "⬜"
                lines.append(f"  {status} #{t['id']}: {t['text']}")
            return [{"type": "text", "text": "\n".join(lines)}]
        elif action == "done":
            tid = arguments.get("id")
            if tid is None:
                return [{"type": "text", "text": "❌ 'id' is required for done action"}]
            for t in todos:
                if t["id"] == tid:
                    t["done"] = True
                    return [{"type": "text", "text": f"✅ Marked #{tid} as done: {t['text']}"}]
            return [{"type": "text", "text": f"❌ Todo #{tid} not found"}]
        elif action == "clear":
            count = len(todos)
            todos.clear()
            return [{"type": "text", "text": f"🗑️ Cleared {count} todos"}]

    return [{"type": "text", "text": f"Unknown tool: {name}"}]

# ── Main Entry ──────────────────────────────────────────────
async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationCapabilities(
                sampling={},
                experimental={},
            ),
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

python3 server.py --help  # Should not crash

# Press Ctrl+C to stop (it runs as a long-lived process)

{
  "mcpServers": {
    "my-tools": {
      "command": "python3",
      "args": ["/absolute/path/to/my-mcp-server/server.py"],
      "env": {}
    }
  }
}

claude

> What's the weather in Tokyo?

> Summarize the file /Users/you/project/README.md

> Add "Buy groceries" to my todo list

pip install httpx

import httpx

# Add your API key (get one free at https://openweathermap.org/api)
OPENWEATHER_API_KEY = os.environ.get("OPENWEATHER_API_KEY", "your-key-here")

# ... inside call_tool, replace the get_weather block:

elif name == "get_weather":
    city = arguments["city"]
    units = arguments.get("units", "celsius")
    unit_param = "metric" if units == "celsius" else "imperial"

    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.openweathermap.org/data/2.5/weather",
            params={"q": city, "appid": OPENWEATHER_API_KEY, "units": unit_param},
            timeout=10.0
        )

    if resp.status_code == 404:
        return [{"type": "text", "text": f"❌ City not found: {city}"}]
    elif resp.status_code != 200:
        return [{"type": "text", "text": f"❌ API error: {resp.status_code}"}]

    data = resp.json()
    temp = data["main"]["temp"]
    condition = data["weather"][0]["description"]
    humidity = data["main"]["humidity"]
    symbol = "°C" if units == "celsius" else "°F"

    return [{
        "type": "text",
        "text": f"📍 {data['name']}: {temp}{symbol}, {condition.title()}, Humidity: {humidity}%"
    }]

{
  "mcpServers": {
    "my-tools": {
      "command": "python3",
      "args": ["/absolute/path/to/my-mcp-server/server.py"],
      "env": {
        "OPENWEATHER_API_KEY": "your-real-api-key"
      }
    }
  }
}