python-mcp-server-template

# {{PROJECT_NAME}} {{PROJECT_DESCRIPTION}} This is an MCP (Model Context Protocol) server template that provides AI agents access to your API endpoints. It's built with Python and can be run using uv package manager or Docker. ## Setup ### Prerequisites - Python 3.13 or higher (latest stable) - [uv package manager](https://github.com/astral-sh/uv) (or Docker) ### Method 1: Local Development with uv 1. **Install uv** (if not already installed): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Install dependencies**: ```bash uv sync ``` 3. **Configure environment variables**: ```bash cp .env.example .env # Edit .env with your API configuration ``` 4. **Run the server**: ```bash uv run python -m src.server ``` ### Method 2: Docker 1. **Configure environment variables**: ```bash cp .env.example .env # Edit .env with your API configuration ``` 2. **Build and run with Docker Compose**: ```bash docker-compose up --build ``` Or build and run manually: ```bash docker build -t my-mcp-server . docker run --rm -it --env-file .env my-mcp-server ``` ## Available Tools - `get_users`: Retrieve users from the API - `create_user`: Create a new user - `get_user_by_id`: Get user by ID ## Configuration Set these environment variables in your `.env` file: - `API_BASE_URL`: Base URL of your existing API (default: http://localhost:8000) - `API_KEY`: API authentication key (optional) ### Docker-specific Notes - The default `API_BASE_URL` in Docker is set to `http://host.docker.internal:8000` to access services on the host machine - Adjust the `docker-compose.yml` file if you need to expose ports or use different networking ## Connecting to AI Clients To connect this MCP server to an AI client like Claude Desktop, add this configuration: ### Local Development ```json { "mcpServers": { "{{PROJECT_NAME}}": { "command": "uv", "args": ["run", "python", "-m", "src.server"], "cwd": "/path/to/{{PROJECT_NAME}}" } } } ``` ### Docker ```json { "mcpServers": { "{{PROJECT_NAME}}": { "command": "docker", "args": ["run", "--rm", "-i", "--env-file", "/path/to/{{PROJECT_NAME}}/.env", "{{PROJECT_NAME}}"], "cwd": "/path/to/{{PROJECT_NAME}}" } } } ``` ## Development ### Testing ```bash # Run tests with uv uv run pytest # Or create a simple test uv run python test_server.py ``` ### Customization **To adapt this for your specific API:** 1. **Update `src/tools.py`:** - Replace the example tools with your actual API endpoints - Modify the `APIClient.make_request()` method if you need custom authentication - Update the `handle_tool_call()` function with your endpoint logic 2. **Update `src/config.py`:** - Add any additional configuration your API needs - Modify authentication settings 3. **Add more sophisticated error handling:** - Handle specific HTTP status codes - Add retry logic for transient failures - Implement proper logging ## Project Structure ``` {{PROJECT_NAME}}/ ├── src/ │ ├── __init__.py │ ├── server.py # Main MCP server implementation │ ├── tools.py # Tool definitions and API client │ └── config.py # Configuration management ├── pyproject.toml # Project configuration and dependencies ├── docker-compose.yml # Docker Compose configuration ├── Dockerfile # Docker image definition ├── .env.example # Example environment variables ├── .gitignore # Git ignore patterns ├── .dockerignore # Docker ignore patterns └── README.md # This file ```