shazaaly/mcp-boilerplate

MCP Server

A Model Context Protocol (MCP) server built with FastMCP that provides tools, resources, and prompts for greeting, math operations, user management, and system monitoring.

Features

• Tools: Greeting, math operations (add/multiply), user information lookup
• Resources: Server info, user data, configuration settings
• Prompts: User analysis, report generation, system health checks, troubleshooting

Quick Start

Prerequisites

• Python 3.12 or higher
• uv (recommended) or pip

Installation Options

Option 1: Install from PyPI (Recommended)

# Install with uv (recommended)
uv add mcp-server-boilerplate

# Or install with pip
pip install mcp-server-boilerplate  # not published , this is boilerplate

After installation, you can run the server directly:

mcp-server-boilerplate

Option 2: Install from GitHub (Development)

1. Clone the repository:

git clone <YOUR_GITHUB_REPO_URL>
cd mcp_server

2. Install uv (if not already installed):

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

3. Install dependencies:

uv sync

Alternative with pip:

pip install fastmcp>=2.11.3

4. Test the server:

uv run python main.py

You should see the FastMCP banner and server startup message. Press Ctrl+C to stop.

Available Tools

• greet(name: str) - Greet a person by name
• add(a: int, b: int) - Add two numbers together
• multiply(a: int, b: int) - Multiply two numbers together
• get_user_info(user_id: int) - Get user information by ID

Connecting to Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your configuration file.

Step 1: Find Your Config File

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Find Your Paths

First, find the required paths for your system:

# Find uv installation path
which uv

# Get your current directory
pwd

Step 3: Add Server Configuration

If Installed from PyPI

Add this to your claude_desktop_config.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "mcp-server-boilerplate": {
      "command": "mcp-server-boilerplate"
    }
  }
}

If Installed from GitHub (Development)

{
  "mcpServers": {
    "mcp-server-boilerplate": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "python",
        "main.py"
      ],
      "cwd": "/path/to/your/mcp_server"
    }
  }
}

Important: Replace the paths with your actual values:

• Replace /path/to/uv with the output from which uv
• Replace /path/to/your/mcp_server with your project directory path

After adding the configuration, restart Claude Desktop to load the MCP server.

Testing with MCP Inspector

To test your server with MCP Inspector:

1. Start the server in one terminal:

uv run python main.py

2. In MCP Inspector, use these connection settings:
   • Connection Type: Local Command
   • Command: /home/shaza/.local/bin/uv (use which uv to find your path)
   • Arguments: run python main.py
   • Working Directory: /home/shaza/shaza/mcp_server

Or alternatively, if using direct python:

• Command: python3
• Arguments: main.py
• Working Directory: /home/shaza/shaza/mcp_server

Troubleshooting

Common Issues

1. "ModuleNotFoundError: No module named 'fastmcp'"

# Install dependencies
uv sync
# or
pip install fastmcp>=2.11.3

2. "python: command not found"

• Use python3 instead of python
• Make sure Python 3.12+ is installed

3. "uv: command not found"

• Install uv following the installation instructions above
• Or use the direct Python configuration in Claude Desktop

4. Claude Desktop connection issues

• Verify all paths in your config are absolute (not relative)
• Restart Claude Desktop after config changes
• Check that the config file is valid JSON (no trailing commas)
• Test the server runs manually first: uv run python main.py

5. MCP Inspector connection errors

• Make sure the server isn't already running in another terminal
• Use absolute paths for command and working directory
• Verify uv is in your PATH

Getting Help

1. Test the server manually: uv run python main.py
2. Check your paths with which uv and pwd
3. Validate your JSON config at jsonlint.com
4. Check Claude Desktop logs for error messages

Development

Project Structure

• main.py - Entry point that starts the MCP server
• server.py - Main server code with tools, resources, and prompts
• pyproject.toml - Python project configuration and dependencies

Adding New Features

• Tools: Add functions decorated with @mcp.tool in server.py
• Resources: Add functions decorated with @mcp.resource("uri")
• Prompts: Add functions decorated with @mcp.prompt

All functions should include proper type hints and docstrings for the best experience.

Publishing to PyPI (For Maintainers)

First Time Setup

1. Install build tools:

uv add --dev build twine

2. Create PyPI account at pypi.org

3. Configure authentication:

# Create API token at https://pypi.org/manage/account/token/
# Store it securely - you'll use it as password with username '__token__'

Publishing Process

1. Update version in pyproject.toml and mcp_server_boilerplate/__init__.py

2. Build the package:

uv run python -m build

3. Test upload to TestPyPI (recommended first time):

uv run twine upload --repository testpypi dist/*

4. Upload to PyPI:

uv run twine upload dist/*

Updating the Package

1. Update version numbers in:

   • pyproject.toml
   • mcp_server_boilerplate/__init__.py

2. Clean previous builds:

rm -rf dist/ build/ *.egg-info/

3. Build and upload:

uv run python -m build
uv run twine upload dist/*

Before You Publish

• Update GitHub URLs in pyproject.toml
• Test the package locally: uv run mcp-server-boilerplate
• Add your email to pyproject.toml authors section
• Ensure all sensitive information is removed