FastMCP Server Boilerplate
A comprehensive boilerplate for building MCP (Model Context Protocol) servers using FastMCP. This boilerplate includes example tools, resources, and prompts to help you get started quickly.
Features
- 🛠️ Example Tools: Ready-to-use tools for text analysis, calculations, and more
- 📚 Resources: Sample resource endpoints for data access
- 💬 Prompts: Predefined prompt templates for common tasks
- 🐳 Docker Support: Fully containerized with optimized Dockerfile
- ⚡ uv Package Manager: Fast dependency management with uv
- 🔧 Type Hints: Full type annotation support for better IDE experience
What's Included
Tools
get_greeting: Generate personalized greetingscalculate_sum: Perform mathematical calculationsanalyze_text: Analyze text and return statistics
Resources
info://server/info: Server information and metadatadata://example/stats: Example statistics data
Prompts
code_review_prompt: Generate code review templatesdata_analysis_prompt: Generate data analysis templates
Prerequisites
- Python 3.12 or higher
- uv package manager
- Docker (optional, for containerized deployment)
Installation
Using uv (Recommended)
- Clone or copy this boilerplate:```bash
cd /path/to/mcp-boilerplate
2. Install dependencies:```bash
uv sync
- Run the server:```bash
uv run server.py
### Using pip
1. Install dependencies:```bash
pip install "mcp[cli]>=1.6.0"
- Run the server:```bash
python server.py
## Docker Deployment
### Build the Docker image:```bash
docker build -t mcp-boilerplate .
Run the container:```bash
docker run -i mcp-boilerplate
### Using docker-compose (create docker-compose.yml):```yaml
version: '3.8'
services:
mcp-server:
build: .
stdin_open: true
tty: true
Then run:```bash
docker-compose up
## Project Structure```
mcp-boilerplate/
├── server.py # Main MCP server implementation
├── pyproject.toml # Project dependencies and metadata
├── Dockerfile # Docker configuration
├── README.md # This file
└── .gitignore # Git ignore patterns
Usage Example
The MCP server communicates via stdio (standard input/output). Here's how to interact with it:
Testing Tools
Tools can be called by LLM clients or testing frameworks that support MCP:```python
Example: Using the calculate_sum tool
{
"method": "tools/call",
"params": {
"name": "calculate_sum",
"arguments": {
"numbers": [1, 2, 3, 4, 5]
}
}
}
### Accessing Resources
Resources provide read-only data access:```python
# Example: Accessing server info
{
"method": "resources/read",
"params": {
"uri": "info://server/info"
}
}
Customization
Adding New Tools
-
Add a new function with the
@mcp.tool()decorator:```python
@mcp.tool()
async def your_custom_tool(param: str) -> Dict[str, Any]:
"""
Your tool description here.Args:
param: Parameter descriptionReturns:
Result description
"""Your implementation
return {"result": "value"}
### Adding New Resources
1. Add a new function with the `@mcp.resource()` decorator:```python
@mcp.resource("custom://your/resource")
async def your_custom_resource() -> str:
"""
Your resource description here.
Returns:
Resource data as string
"""
return "your data"
Adding New Prompts
-
Add a new function with the
@mcp.prompt()decorator:```python
@mcp.prompt()
async def your_custom_prompt(param: str = "default") -> str:
"""
Your prompt description here.Args:
param: Parameter descriptionReturns:
Formatted prompt string
"""
return f"Your prompt template with {param}"
## Development
### Install development dependencies:```bash
uv sync --extra dev
Run tests (if you add them):```bash
uv run pytest
### Format code:```bash
uv run black .
Lint code:```bash
uv run ruff check .
```
Configuration
You can configure the server by modifying server.py:
- Server Name: Change the name in
FastMCP("Your Server Name") - Transport: Currently uses
stdio, can be changed tossefor HTTP transport - Environment Variables: Add custom env vars in the Dockerfile
Troubleshooting
Server not responding
- Ensure Python 3.12+ is installed
- Check that all dependencies are installed correctly
- Verify stdin/stdout are not being used by other processes
Docker build fails
- Ensure Docker is running
- Check network connectivity for downloading uv and dependencies
- Verify pyproject.toml syntax is correct
Import errors
- Run
uv syncto ensure all dependencies are installed - Check Python version compatibility
Resources
- FastMCP Documentation
- MCP Specification
- uv Package Manager
License
This boilerplate is provided as-is for educational and development purposes.
Contributing
Feel free to customize this boilerplate for your specific use case. Common modifications include:
- Adding database connections
- Integrating external APIs
- Adding authentication
- Implementing custom business logic
Next Steps
- Customize the example tools to match your use case
- Add your own resources and prompts
- Configure the server name and metadata
- Add tests for your custom functionality
- Deploy using Docker or your preferred method
Happy building! 🚀
