FastMCP Starter Documentation

Overview

FastMCP Starter is a template project for building Model Context Protocol (MCP) servers using the FastMCP framework. This starter provides a simple example server with a basic tool implementation.

Features

• FastMCP framework integration
• HTTP transport support
• Docker containerization
• Example tool implementation (add function)
• Health check endpoint
• Production-ready setup

Project Structure

fastmcp-starter/
├── src/
│   └── starter/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml             # Project dependencies
├── Dockerfile                  # Docker image configuration
├── docker-compose.yml          # Docker Compose configuration
└── docs.md                     # This file

Requirements

• Python 3.13+
• uv (Python package manager)
• Docker and Docker Compose (optional, for containerized deployment)

Installation

Local Development

1. Install uv (if not already installed):

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install dependencies:

uv sync

Running the Server

Local Development

Run the server directly:

uv run python src/starter/server.py

Docker Deployment

Build and run using Docker Compose:

docker-compose up --build

Or using Docker directly:

docker build -t fastmcp-starter .
docker run -p 8000:8000 fastmcp-starter

API Endpoints

MCP Endpoint

MCP is available at:

http://127.0.0.1:8000/mcp

This is the main endpoint for MCP protocol communication. Clients should connect to this endpoint to interact with the MCP server.

Health Check

The server includes a health check endpoint (used by Docker health checks):

http://localhost:8000/health

Available Tools

add

Adds two numbers together.

Parameters:

• a (int): First number
• b (int): Second number

Returns:

• int: Sum of a and b

Example:

result = add(5, 3)  # Returns 8

Configuration

Server Configuration

The server is configured in src/starter/server.py:

mcp.run(transport="http", host="0.0.0.0", port=8000)

• transport: Protocol transport type (currently "http")
• host: Bind address (0.0.0.0 for all interfaces)
• port: Server port (8000)

Docker Configuration

Ports

• 8000: MCP server port (mapped to host port 8000)

Development

Adding New Tools

To add a new tool to the MCP server, use the @mcp.tool decorator in src/starter/server.py:

@mcp.tool
def your_tool(param1: str, param2: int) -> str:
    """Tool description"""
    # Your implementation here
    return result

Project Dependencies

Dependencies are managed in pyproject.toml:

• fastmcp>=2.13.1: FastMCP framework

To add new dependencies:

uv add package-name

Troubleshooting

Port Already in Use

If port 8000 is already in use, you can:

1. Change the port in src/starter/server.py
2. Update the port mapping in docker-compose.yml
3. Stop the service using port 8000

Docker Issues

If the container fails to start:

1. Check Docker logs: docker-compose logs
2. Verify the Dockerfile builds correctly: docker build -t fastmcp-starter .
3. Ensure port 8000 is not in use on the host

License

This is a starter template project. Add your license information here.

Contributing

This is a starter template. Customize as needed for your project.