Python FastMCP Template

A template for creating Model Context Protocol (MCP) servers using Python and FastMCP.

Overview

This template provides a foundation for building MCP servers with support for two transport protocols:

• STDIO (default) - Standard input/output communication
• SSE - Server-Sent Events over HTTP

Features

• Easy configuration switching between STDIO and SSE protocols
• Automatic mcp.json configuration generation
• Example tool implementation (mcp_get_precise_time)
• Clean project structure with modular components

File Structure

├── mcp_server.py                    # Main MCP server application
├── mcp_settings.py                  # Configuration settings
├── mcp_transport_configurator.py    # Auto-configures mcp.json
├── mcp_util.py                      # Utility functions (add your tools here)
├── requirements.txt                 # Python dependencies
└── README.md                        # This file

Setup

1. Install dependencies:

   pip install -r requirements.txt
   

2. Configure transport protocol: Edit mcp_settings.py to choose your transport protocol:

   SETTINGS = {
       PROTOCOL : STDIO,  # or SSE
       PORT     : "5500"  # only used for SSE
   }
   

Transport Protocols

STDIO (Default)

• Uses standard input/output for communication
• Suitable for direct integration with clients that support process spawning
• Configuration is automatically generated for VS Code MCP extension

SSE (Server-Sent Events)

• HTTP-based communication using Server-Sent Events
• Runs on configurable port (default: 5500)
• Suitable for web-based integrations or when firewall restrictions apply

Running the Server

Method 1: Direct execution (Recommended)

python mcp_server.py

This will:

1. Automatically configure the appropriate mcp.json file
2. Start the server with the selected transport protocol

Method 2: Configuration only

To just update the mcp.json configuration without starting the server:

python mcp_transport_configurator.py

Configuration Files

The server automatically generates .vscode/mcp.json based on your protocol choice.

Notes about generated configuration

• The configurator writes .vscode/mcp.json into the current working directory (cwd). The generated configuration embeds the VS Code placeholder ${workspaceFolder} (not ${cwd}) in command/args/env entries so VS Code resolves paths relative to the workspace when the MCP extension runs the agent.
• For STDIO mode the configurator picks an OS-appropriate Python executable inside .venv:
  • Windows: .venv\\Scripts\\python.exe
  • macOS/Linux: .venv/bin/python

Path-separator note

• The configurator uses Python path utilities when constructing the placeholder-containing strings. On Windows this results in backslashes (\) inside the generated JSON values; on POSIX systems it uses forward slashes (/). Because VS Code expands ${workspaceFolder} at runtime, mixed or platform-specific separators may appear after expansion. If you need perfectly normalized paths in your workspace configuration, consider either:
  • Using forward slashes in the JSON (e.g. ${workspaceFolder}/.venv/...), or
  • Using the per-platform overrides in launch.json/configuration blocks.

STDIO Configuration (examples)

Windows (what the configurator may produce when run on Windows):

{
    "servers": {
        "my-mcp-server": {
            "command": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
            "args": ["${workspaceFolder}\\agent_tpl\\mcp_server.py"],
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    }
}

macOS / Linux (what the configurator may produce when run on POSIX):

{
    "servers": {
        "my-mcp-server": {
            "command": "${workspaceFolder}/.venv/bin/python",
            "args": ["${workspaceFolder}/agent_tpl/mcp_server.py"],
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    }
}

SSE Configuration (example)

{
    "servers": {
        "my-sse-mcp-server": {
            "type": "sse",
            "url": "http://127.0.0.1:5500/sse"
        }
    }
}

Adding Your Own Tools

1. Implement your functions in mcp_util.py
2. Add MCP tool wrappers in mcp_server.py using the @app.tool() decorator

Example:

# In mcp_util.py
def my_custom_function(param1, param2):
    """Your custom logic here"""
    return f"Result: {param1} + {param2}"

# In mcp_server.py
@app.tool()
def my_custom_tool(param1: str, param2: str):
    """
    Description of what this tool does
    """
    return my_custom_function(param1, param2)

Troubleshooting

Common Issues

1. Port already in use (SSE mode):

   • Change the port in mcp_settings.py
   • Check if another service is using the port

2. Python path issues (STDIO mode):

   • Ensure you're using a virtual environment
   • Verify the Python path in the generated mcp.json

3. Module import errors:

   • Check that all dependencies are installed
   • Verify PYTHONPATH is set correctly

Logs and Debugging

• STDIO mode: Check VS Code MCP extension logs
• SSE mode: Server logs are printed to console

Sample prompt

Tell me the precise time (using MCP Tools).

License

This template is provided as-is for educational and development purposes.

Author

GUU8HC