Claude MCP Server — Starter Template

A clean, production-quality MCP (Model Context Protocol) server template for Claude Code and Claude Desktop. Includes 3 ready-to-use tool modules and a simple pattern for adding your own in minutes.

MCP is the skill that lets you turn Claude into a custom AI agent for any system. This is the template that shows you how.

What is MCP?

MCP (Model Context Protocol) lets Claude call tools you define on your own machine. When Claude needs to search files, hit an API, or transform data — it sends a JSON-RPC request to your local server, your code runs, and Claude gets the result. Your data never leaves your machine.

Claude Code / Claude Desktop
          │
          │  JSON-RPC over stdio
          ▼
   ┌─────────────────┐
   │   server.py     │   ← MCP server (this repo)
   │   (MCP host)    │
   └────────┬────────┘
            │
     ┌──────┼──────┐
     ▼      ▼      ▼
   File    Web    Data
  Search  Fetch  Transform

The protocol is open, vendor-neutral, and supported natively in Claude Code CLI and Claude Desktop. Once you have a working MCP server, every tool you add is instantly available to Claude — no API wrappers, no cloud functions, no rate limits beyond your own.

Included Tools

Quick Start

1. Clone and install

git clone https://github.com/JustDreameritis/claude-mcp-starter.git
cd claude-mcp-starter
pip install -r requirements.txt

Python 3.10+ required.

2. Configure for Claude Code

Add to your project's .claude/settings.json (or global ~/.claude/settings.json):

{
  "mcpServers": {
    "starter-tools": {
      "command": "python",
      "args": ["/full/path/to/claude-mcp-starter/server.py"]
    }
  }
}

See .claude/settings.json.example in this repo for the full schema.

3. Configure for Claude Desktop

Add to claude_desktop_config.json (location varies by OS):

{
  "mcpServers": {
    "starter-tools": {
      "command": "python",
      "args": ["/full/path/to/claude-mcp-starter/server.py"]
    }
  }
}

See claude_desktop_config.json.example for the full schema.

4. Start a conversation

Restart Claude Code (or Claude Desktop). The tools will appear automatically. Try:

• "Search for all Python files under /home/me/project"

• "Fetch https://news.ycombinator.com and extract all links"

• "Convert this JSON array to a CSV at /tmp/output.csv"

Environment Variables

Copy .env.example to .env and adjust as needed. The server reads these at startup.

All file tool calls are validated against ALLOWED_DIRECTORIES. Attempts to read outside these paths return a permission error — no silent failures.

Project Structure

claude-mcp-starter/
├── server.py                       # MCP server entry point
├── tools/
│   ├── __init__.py
│   ├── file_search.py              # search_files, read_file_summary
│   ├── web_fetch.py                # fetch_url, extract_links
│   └── data_transform.py          # json_to_csv, csv_stats
├── docs/
│   └── SOW-template.md            # Upwork statement-of-work template
├── .claude/
│   └── settings.json.example      # Claude Code configuration template
├── claude_desktop_config.json.example
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

Adding Your Own Tools

Each tool module follows the same three-part pattern. Creating a new tool takes about 10 minutes.

Step 1 — Create tools/my_tool.py

from mcp.types import Tool, TextContent

MY_TOOLS = [
    Tool(
        name="my_tool_name",
        description="One clear sentence describing what this tool does.",
        inputSchema={
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "What this parameter is for.",
                },
                "param2": {
                    "type": "integer",
                    "description": "Optional count. Default: 10.",
                    "default": 10,
                },
            },
            "required": ["param1"],
        },
    ),
]


async def _my_tool_handler(arguments: dict) -> list[TextContent]:
    param1 = arguments.get("param1", "")
    param2 = int(arguments.get("param2", 10))

    if not param1:
        raise ValueError("'param1' is required.")

    # Your logic here
    result = f"Processed '{param1}' with count={param2}."
    return [TextContent(type="text", text=result)]


MY_HANDLERS = {
    "my_tool_name": _my_tool_handler,
}

Step 2 — Register in server.py

from tools.my_tool import MY_TOOLS, MY_HANDLERS

ALL_TOOLS.extend(MY_TOOLS)
TOOL_HANDLERS.update(MY_HANDLERS)

Step 3 — Restart Claude Code

That's it. Your tool is live.

Architecture Notes

Why stdio transport?

MCP servers communicate with Claude via stdin/stdout using JSON-RPC 2.0. Claude Code spawns the server as a subprocess and manages the lifecycle. This means:

• No network port to open or firewall to configure

• Server starts and stops with Claude

• Logs go to stderr (visible in Claude Code's MCP debug output)

• Multiple MCP servers can run simultaneously without conflicts

Handler dispatch pattern

server.py uses a central dispatch table rather than decorating individual handlers per-tool. This keeps modules independent — each exports a plain dict — and makes it trivial to register, inspect, or disable tools at startup without touching tool code.

Error handling

All tool errors are caught in server.py's call_tool dispatcher and returned as TextContent responses. This means Claude always gets a useful error message instead of a protocol-level failure, and can reason about what went wrong and try an alternative approach.

Running the Server Directly (for debugging)

python server.py

The server will wait for JSON-RPC input on stdin. You can test with raw JSON:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python server.py

Or enable debug logging:

LOG_LEVEL=DEBUG python server.py

Tech Stack

• Python 3.10+

• mcp — Anthropic's official MCP SDK

• httpx — Async HTTP client for web fetch tools

• chardet — Encoding detection for file tools

• Standard library only for everything else (csv, json, glob, pathlib)

Security Considerations

• File tools validate all paths against ALLOWED_DIRECTORIES before any I/O

• fetch_url enforces a response size cap (MAX_FETCH_SIZE_KB) to prevent memory exhaustion

• File read tools enforce a file size cap (MAX_FILE_SIZE_MB)

• HTTP requests use a 15-second timeout

• No shell execution, no subprocess spawning, no eval

For production team deployments, consider adding per-tool authentication and audit logging.

Freelance / Upwork

Want to offer this as a service? See docs/SOW-template.md for a ready-to-use Statement of Work covering discovery, development, testing, and documentation phases — with tiered pricing from $150 to $800 depending on complexity.

MCP development is an emerging skill with very few practitioners and significant demand as teams start integrating Claude into their internal tooling.

License

MIT — use it, fork it, sell services with it.

Built by JustDreameritis