MCP Starter Template

A comprehensive starter template for building MCP (Model Context Protocol) servers using Python and FastMCP.

Features

• FastMCP Integration: Built on the modern FastMCP framework for easy tool development
• CLI Interface: Command-line interface for easy server management
• Environment Configuration: Support for environment variables and command-line arguments
• Development Mode: Built-in development server with MCP Inspector support
• Testing Framework: Example tests and testing utilities
• Modern Python Packaging: Uses pyproject.toml with setuptools backend
• Installation Helpers: Scripts for easy installation and deployment

Quick Start

1. Clone and Customize

# Copy this template to your project
cp -r mcp-starter my-mcp-server
cd my-mcp-server

# Customize the project
# Edit pyproject.toml, setup.py, and other files to match your project

2. Install Dependencies

# Install in development mode
pip install -e .

# Or install from PyPI (after publishing)
pip install my-mcp-server

3. Run the Server

# Run with default settings
my-mcp-server

# Run with custom settings
my-mcp-server --host 0.0.0.0 --port 9000

# Run in development mode with MCP Inspector
my-mcp-server --dev

# Install in Claude Desktop
my-mcp-server --install

Project Structure

mcp-starter/
├── README.md                 # This file
├── pyproject.toml            # Modern Python packaging configuration
├── setup.py                  # Backward compatibility setup
├── requirements.txt          # Dependencies
├── server/           # Main package directory
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main server implementation
│   └── cli.py               # Command-line interface
├── tests/                   # Test files
│   ├── test_server.py       # Server tests
│   └── test_client.py       # Client tests
└── examples/                # Usage examples
    └── example_client.py    # Example client code

Customization Guide

1. Update Project Metadata

Edit pyproject.toml and setup.py:

• Change project name, description, author
• Update dependencies
• Modify entry points

2. Implement Your Tools

Edit server/server.py:

• Replace example tools with your own
• Add your business logic
• Configure server settings

3. Customize CLI

Edit server/cli.py:

• Add custom command-line arguments
• Modify installation behavior
• Add environment variable support

Example Tools

The starter includes these example tools:

hello_world

A simple greeting tool that demonstrates basic tool structure.

echo_message

An echo tool that shows parameter handling and validation.

get_system_info

A system information tool that demonstrates data collection and formatting.

Configuration

Environment Variables

• MCP_HOST: Server host (default: 127.0.0.1)
• MCP_PORT: Server port (default: 8000)
• MCP_PATH: MCP endpoint path (default: /mcp)

Command Line Arguments

my-mcp-server --help

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "my-mcp-server"
    }
  }
}

Cursor

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "my-mcp-server"
    }
  }
}

Development

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test
python -m pytest tests/test_server.py

Development Mode

# Run with MCP Inspector
my-mcp-server --dev

Building and Publishing

# Build package
python -m build

# Publish to PyPI
python -m twine upload dist/*

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For questions and support:

• Check the documentation
• Open an issue on GitHub
• Join the MCP community discussions