Template

A practical Cookiecutter template for building MCP servers that connect Claude AI to external APIs. Built with FastMCP and ready for Render.com deployment.

Key Features

• Multi-Platform Compatibility: Works with Claude Desktop, Claude Web, and Claude API
• Comprehensive Auth Support: API Key, Bearer Token, OAuth2, Basic Auth
• Rate Limiting: Configurable request throttling to avoid API limits
• Ready-to-Use Tools: 6 pre-built generic API tools adaptable to any service
• One-Click Deployment: Render.com integration with pre-configured settings
• Docker Support: Containerization for cloud deployments (beta - community testing welcome)
• Robust Error Handling: Detailed error reporting and recovery
• Testable Components: Each module can be tested independently
• Session Management: Prevents "Event loop is closed" errors

What This Does

This template generates a complete MCP server project that lets Claude AI interact with any API. Think of it as a bridge between Claude and the external services you want to use.

Example scenarios:

• Weather data from meteorological services
• News headlines from news APIs
• Stock prices from financial data providers
• Social media posts from platform APIs
• E-commerce data from marketplace APIs

Tech Stack

• FastMCP - Python framework for MCP servers (v0.4.0+)
• aiohttp - Async HTTP client for API calls
• Pydantic - Configuration management
• Render.com - One-click deployment

Requirements: Python 3.11 or newer

Quick Start

1. Generate Your Project

pip install cookiecutter
cookiecutter https://github.com/pietroperona/mcp-server-template

You'll be asked a few questions:

project_name: News API Server
project_slug: news-api-server  [auto-generated]
author_name: Your Name
author_email: you@example.com
github_username: yourusername
api_base_url: https://newsapi.org/v2
api_service_type: REST API
auth_type: API Key
include_rate_limiting: yes
include_caching: no
render_deployment: yes
docker_support: yes
license: MIT

2. Configure Your API

cd news-api-server
cp .env.example .env

Edit .env with your API credentials:

API_BASE_URL=https://newsapi.org/v2
API_KEY=your_news_api_key

3. Install and Run

pip install -r requirements.txt
python main.py

Your MCP server is now running at http://localhost:8000

4. Connect to Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "news-api": {
      "command": "python",
      "args": ["news-api-server/main.py"],
      "cwd": "news-api-server"
    }
  }
}

Now Claude can fetch news: "What are the latest tech headlines?"

5. Connect to Claude Web Browser (Claude.ai)

Your MCP server also exposes an SSE (Server-Sent Events) endpoint at /sse that can be used with Claude Web in browsers:

1. Deploy your MCP server to a public URL (see Deployment section)
2. In Claude Web, go to Settings → Claude API Tools
3. Add your MCP server's public URL + /sse endpoint:

   https://your-mcp-server.onrender.com/sse
   

4. Claude Web will now show your tools in the Tools menu

Note: The /sse endpoint is automatically included in all MCP servers generated with this template.

What You Get

Every generated project includes:

6 Ready-to-Use Tools

• get_api_status - Check if your API is working
• list_resources - Browse available data (articles, users, products, etc.)
• get_resource_by_id - Get specific item details
• create_resource - Add new data
• update_resource - Modify existing data
• delete_resource - Remove data

Real Example: News API

When you ask Claude "Show me recent technology news", here's what happens:

1. Claude calls list_resources(resource_type="articles", category="technology")
2. Your MCP server hits https://newsapi.org/v2/everything?q=technology
3. Claude gets the news data and responds with formatted articles

Project Structure

news-api-server/
├── core/
│   ├── config.py     # API credentials & settings
│   ├── auth.py       # Handle API authentication  
│   └── client.py     # HTTP client with retries
├── tools/
│   └── example_tools.py  # The 6 MCP tools
├── docs/             # Setup guides & troubleshooting
│   ├── configuration.md  # Detailed configuration options
│   ├── quick-start.md    # Getting started guide
│   ├── README.md         # Overview of documentation
│   └── troubleshooting.md # Common issues & solutions
├── main.py          # FastMCP server
└── .env.example     # Configuration template

Note: When your server runs, it may create directories that end with _data/ (like cache_data/). These directories are automatically excluded from git via .gitignore as they contain runtime data that shouldn't be committed.

Authentication Support

The template handles different auth methods:

API Key (most common)

API_KEY=your_key_here
API_KEY_HEADER=X-API-Key

Bearer Token

BEARER_TOKEN=your_token_here

OAuth2 (for complex APIs)

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

Basic Auth

USERNAME=your_username  
PASSWORD=your_password

Production Deployment

Render.com (Recommended)

1. Push your generated project to GitHub
2. Connect to Render.com
3. Set your environment variables
4. Your MCP server is live!

The template includes render.yaml with optimized settings for production.

Important for Claude Web Browser: Make sure to note the public URL of your deployed service. Claude Web will connect to your MCP server via the /sse endpoint:

https://your-service-name.onrender.com/sse

Docker

Note: Docker support is included in the template but has not been extensively tested yet. Community feedback and contributions are welcome.

docker build -t my-mcp-server .
docker run -p 8000:8000 --env-file .env my-mcp-server

For Claude Web: Access the SSE endpoint at http://your-docker-host:8000/sse

Real-World Examples

News Headlines Service

# Generate project
cookiecutter https://github.com/pietroperona/mcp-server-template
# Project: News API Server
# API: NewsAPI.org (free tier)
# Result: Claude can fetch latest news by category/keyword

Try it: NewsAPI.org - 1000 free requests/day

Weather Service

# Generate project
cookiecutter https://github.com/pietroperona/mcp-server-template
# Project: Weather API Server
# API: OpenWeatherMap (free)
# Result: Claude can check weather worldwide

Try it: OpenWeatherMap - Free API with 1000 calls/day

Stock Market Data

# Generate project
cookiecutter https://github.com/pietroperona/mcp-server-template  
# Project: Stock Market Server
# API: Alpha Vantage (free)
# Result: Claude can look up stock prices and market data

Try it: Alpha Vantage - Free API key, 5 calls/minute

Social Media Integration

# Generate project
cookiecutter https://github.com/pietroperona/mcp-server-template
# Project: Social Media Server
# API: Twitter/X API (paid)
# Result: Claude can post tweets and read social media feeds

Detailed Setup Example

Let's walk through building a news API server:

1. Get NewsAPI Key

• Go to newsapi.org
• Sign up for free account
• Copy your API key

2. Generate Project

cookiecutter https://github.com/pietroperona/mcp-server-template

project_name: News API Server
project_slug: news-api-server  
author_name: John Smith
api_service_type: REST API
auth_type: API Key
api_base_url: https://newsapi.org/v2
include_rate_limiting: yes
render_deployment: yes

3. Configure Environment

cd news-api-server
cp .env.example .env

Edit .env:

API_BASE_URL=https://newsapi.org/v2
API_KEY=your_actual_api_key_here
API_KEY_HEADER=X-API-Key

4. Test Your Server

python main.py

5. Test with Claude

Ask Claude: "What are the latest technology headlines?"

Claude will use your tools:

Tool: list_resources
Parameters: resource_type="articles", category="technology"
Result: Latest tech news articles with titles, descriptions, and URLs

Customization

Modify for Your API

The generated tools are generic but easy to customize:

# In tools/example_tools.py
async def list_resources_async(resource_type: str = "articles", category: str = "general"):
    # Customize this for your API
    endpoint = f"/everything?category={category}"
    response = await client.get(endpoint)
    return response

Add API-Specific Tools

@mcp.tool()
def get_headlines_by_category(category: str, country: str = "us") -> str:
    """Get top headlines by category and country"""
    result = run_async_tool(get_headlines_async, category, country)
    return json.dumps(result, indent=2)

Configure Rate Limiting

# In .env
RATE_LIMIT_REQUESTS=60    # 60 requests
RATE_LIMIT_WINDOW=60      # per minute

Troubleshooting

Authentication Issues

"Authentication failed"

• Check your API key is correct
• Verify the API_KEY_HEADER name
• Test API key in browser/Postman first

Tool Connection Issues

"Tools not appearing in Claude"

• Restart Claude Desktop
• Check MCP configuration syntax
• Verify server starts without errors

"Claude Web doesn't show my tools"

• Make sure you're using the correct /sse endpoint
• Check CORS settings if hosting on a custom domain
• Verify your server is publicly accessible

API Connection Issues

"Connection timeout"

• Increase API_TIMEOUT in .env
• Check internet connection
• Verify API endpoint URL

"API versioning problems"

• Some APIs don't use version prefixes in URLs
• Set API_VERSION=none or leave it empty in your .env file
• This template handles version-less APIs automatically

Technical Issues

"Event loop is closed" errors

• This is fixed in the latest template version (July 2025)
• The template now uses a better session management approach for aiohttp
• Each request creates a new session with proper cleanup
• Custom event loop handling prevents these errors

Development

Run Tests

python core/auth.py      # Test authentication
python core/client.py    # Test API connection  
python main.py          # Start MCP server

Debug Mode

DEBUG=true python main.py

Shows detailed request/response logs.

Session Management

This template uses an optimized approach to manage aiohttp sessions:

# Create a new session for each request (prevents "Event loop is closed" errors)
async with aiohttp.ClientSession() as session:
    async with session.request(...) as response:
        # Process response

This pattern ensures that:

• Each HTTP request gets a fresh session
• Sessions are properly closed after use
• No "Event loop is closed" errors occur
• Better handling of asyncio event loops

Known Limitations

• Docker Support: While Dockerfile and docker-compose files are included, Docker deployment has not been extensively tested across different environments. We welcome community feedback and testing.
• OAuth2 Flow: OAuth2 implementation requires manual token exchange - automatic browser-based flow is not yet implemented.

Contributing

1. Fork the repository
2. Test your changes with different API types
3. Update documentation
4. Submit pull request

Why This Template?

Building MCP servers involves a lot of boilerplate:

• Authentication handling
• Error management
• Rate limiting
• Configuration
• Deployment setup

This template gives you all of that instantly, so you can focus on connecting to your specific API.

Built on proven tools: FastMCP for the MCP framework, Model Context Protocol for Claude integration.

Works with:

• Claude Desktop (via local MCP server)
• Claude Web Browser (via /sse endpoint)
• Claude API (via proxy configuration)

License

MIT License - use for any purpose, commercial or personal.

---

Recent Updates

• July 2025: Fixed "Event loop is closed" errors with improved aiohttp session management
• July 2025: Added Claude Web Browser support via /sse endpoint
• July 2025: Improved API versioning with better handling of version-less APIs
• July 2025: Added better error handling and troubleshooting guidance

---

Ready to connect Claude to your favorite API?

pip install cookiecutter
cookiecutter https://github.com/pietroperona/mcp-server-template