rjmoggach/simple-mcp-server

Simple MCP Server

A minimal implementation of the Model Context Protocol (MCP) server using FastMCP. This example demonstrates how to create a simple MCP server that clients like Windsurf IDE and Claude can connect to.

What is MCP?

The Model Context Protocol (MCP) is a standard that connects LLMs with external tools and data sources. MCP servers extend AI capabilities by providing access to specialized tools, external information, and services.

Features

• Dual transport support (HTTP and stdio)
• Simple authentication middleware for HTTP transport
• Example tools implementation
• Compatible with MCP clients like Windsurf IDE and Claude

Prerequisites

• Python 3.11+
• FastMCP - https://github.com/jlowin/fastmcp
• uv - https://docs.astral.sh/uv/

Installation

1. Clone this repository:

   git clone https://github.com/rjmoggach/simple-mcp-server.git
   cd simple-mcp-server
   

2. Install dependencies:

   uv sync
   

Usage

You can run the server in three different modes:

Run with both transports (default)

python run_server.py

This will start the HTTP server on port 9876 and the stdio server simultaneously.

HTTP transport only

python run_server.py --http-only

stdio transport only

python run_server.py --stdio-only

Available Tools

The server provides these example tools:

1. hello_world - A simple greeting tool

   • Parameters:
     • name (string, default: "World"): Name to greet
     • delay (integer, default: 0): Optional delay in seconds
   • Returns: A greeting message

2. get_version - Returns server version information

   • Returns: Version details including server name and API version

3. system_info - Returns basic system information

   • Returns: Python version and platform details

Connecting to AI Systems

Windsurf IDE Configuration

Add the following configuration to your Windsurf IDE settings:

"simple-mcp": {
  "command": "npx",
  "args": [
    "mcp-remote", 
    "http://localhost:9876/", 
    "--allow-http", 
    "--header", 
    "Authorization: Bearer SIMPLE_MCP_SERVER"
  ]
}

Claude Desktop Configuration

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "simple-mcp": {
      "command": "uv",
      "args": [
        "run", 
        "--project", "/path/to/simple-mcp-server", 
        "python", "/path/to/simple-mcp-server/run_server.py", 
        "--stdio-only"
      ],
      "cwd": "/path/to/simple-mcp-server"
    }
  }
}

Replace /path/to/simple-mcp-server with the actual path to your project.

Authentication

For HTTP transport, the server uses a simple token-based authentication:

• Token: SIMPLE_MCP_SERVER (defined in run_server.py)
• Header format: Authorization: Bearer SIMPLE_MCP_SERVER

Extending the Server

To add your own tools, modify the create_mcp_server() function in run_server.py:

@mcp.tool()
async def your_custom_tool(param1: str, param2: int = 0) -> dict:
    """Your custom tool description."""
    # Implementation here
    return {"result": "Your output"}

License