Minimal MCP Server Boilerplate

A minimal Model Context Protocol (MCP) server implementation in Python for testing client-server communication.

What This Does

This boilerplate provides the absolute minimum code needed to:

• ✅ Connect with MCP clients (Cursor, Claude Desktop, etc.)

• ✅ Respond to initialization requests

• ✅ List available tools

• ✅ Execute a simple "hello" tool

Related MCP server: Test MCP

Quick Start

1. Prerequisites

• Python 3.9 or higher

• No external dependencies required!

2. Test Locally

# Make server executable
chmod +x server.py

# Run the test client
python test_client.py

You should see:

============================================================
Testing MCP Server
============================================================

1. Testing initialize...
✓ Initialize successful
  Server: minimal-mcp-server

2. Testing tools/list...
✓ Found 1 tool(s):
  - hello: A simple hello tool to test MCP connection

3. Testing tools/call (hello)...
✓ Tool call successful:
  Hello, Developer! MCP connection is working! 🎉

============================================================
All tests passed! 🎉
============================================================

Connecting to MCP Clients

Cursor IDE

1. Find your Cursor MCP config file:

   • macOS: ~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

   • Windows: %APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

   • Linux: ~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

2. Add this configuration (update paths to match your system):

   {
     "mcpServers": {
       "minimal-mcp-server": {
         "command": "python3",
         "args": ["/absolute/path/to/mcp-boilerplate/server.py"],
         "cwd": "/absolute/path/to/mcp-boilerplate"
       }
     }
   }

3. Restart Cursor and verify connection in settings

4. Test: Ask Cursor to "Call the hello tool with name 'YourName'"

Claude Desktop

1. Find Claude's config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the same configuration as above

3. Restart Claude Desktop

4. Test: Ask Claude to use the hello tool

Project Structure

mcp-boilerplate/
├── server.py          # Main MCP server implementation
├── test_client.py     # Local testing script
├── requirements.txt   # Dependencies (empty - uses stdlib)
├── mcp-config.json    # Example client configuration
└── README.md          # This file

How It Works

MCP Protocol Flow

1. Initialize: Client sends initialization request

   {"method": "initialize", "params": {...}}

2. List Tools: Client requests available tools

   {"method": "tools/list"}

3. Call Tool: Client executes a tool

   {"method": "tools/call", "params": {"name": "hello", "arguments": {...}}}

Key Components

• MinimalMCPServer: Main server class

• get_tools(): Returns tool definitions

• call_tool(): Executes tool logic

• handle_request(): Routes JSON-RPC requests

• run_stdio(): Main loop reading from stdin, writing to stdout

Extending the Boilerplate

Adding a New Tool

1. Add tool definition in get_tools():

   {
       "name": "my_tool",
       "description": "Does something useful",
       "inputSchema": {
           "type": "object",
           "properties": {
               "param": {"type": "string", "description": "..."}
           },
           "required": ["param"]
       }
   }

2. Add handler in call_tool():

   if name == "my_tool":
       result = do_something(arguments.get("param"))
       return {"type": "text", "text": result}

Adding Dependencies

If you need external libraries:

1. Add to requirements.txt:

   requests>=2.31.0

2. Install:

   pip install -r requirements.txt

Troubleshooting

Server not connecting?

• Verify Python path is correct in config

• Use absolute paths (not relative)

• Check file permissions (chmod +x server.py)

"Method not found" errors?

• Ensure method names match exactly (case-sensitive)

• Check JSON-RPC format is correct

Server crashes?

• Verify Python 3.9+ is installed

• Check for syntax errors: python -m py_compile server.py

Next Steps

Once connection is verified:

• Add your custom tools

• Integrate with databases, APIs, or services

• Add error handling and logging

• Implement MCP resources and prompts

Resources

• MCP Specification

• MCP Python SDK

• Example Servers

License

MIT License - feel free to use this boilerplate for your projects!