mcp -template

This MCP server template provides a Python-based bridge between Claude AI and external APIs using FastMCP. It exposes a set of six ready-to-use tools that allow Claude to explore, query, create, update, and delete resources from any RESTful API. The server is designed to be deployed with Render or via Docker, and it includes optional authentication, rate limiting, and caching features to help manage API usage. To connect Claude to your API, configure the mcpServers entry in Claude’s MCP settings to point to the local or public URL of the server and rely on the template’s built-in tools to perform common operations such as listing resources, fetching resources by ID, and creating or updating records. The template also supports an SSE endpoint at /sse for Claude Web integration, enabling real-time tool discovery in the browser.

Prerequisites:

• Python 3.11 or newer
• pip
• Optional: cookiecutter if you want to generate a new project from the template

Install and run the template locally:

1. Install cookiecutter (optional if you’re cloning the template directly):

pip install cookiecutter

2. Generate a new MCP server project from the template (optional):

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

3. Navigate to your project directory (the generated folder usually contains a main.py and a requirements.txt):

cd your-project-name

4. Create and activate a Python virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate     # on Windows

5. Install dependencies:

pip install -r requirements.txt

6. Run the MCP server:

python main.py

The server should start and be accessible at http://localhost:8000 (default). If you deploy to Render or Docker, follow the deployment steps in the README to expose the /sse endpoint for Claude Web integration.

• The template includes an SSE endpoint at /sse which Claude Web uses to list and access tools in real-time. Ensure this endpoint is publicly reachable when deploying.
• Environment variables are used for API credentials and config (e.g., API_BASE_URL, API_KEY, BEARER_TOKEN, CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD). Populate a .env file or your deployment environment accordingly.
• The six built-in tools are designed to be generic; you can customize their behavior by modifying the tools under the tools/ directory and updating auth/config handling in core/config.py as needed.
• For production deployments (Render or Docker), set appropriate rate limits and caching policies to avoid hitting upstream API limits.
• If you encounter issues with event loop errors in Claude, verify that session management is correctly enabled and that the server process aligns with your Python environment version.