MCP Boilerplate Server

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)

After installation, you can run the server directly:

Option 2: Install from GitHub (Development)

1. Clone the repository:

2. Install uv (if not already installed):

3. Install dependencies:

Alternative with pip:

4. Test the server:

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:

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):

If Installed from GitHub (Development)

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:

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'"

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:

2. Create PyPI account at pypi.org
3. Configure authentication:

Publishing Process

1. Update version in pyproject.toml and mcp_server_boilerplate/__init__.py
2. Build the package:

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

4. Upload to PyPI:

Updating the Package

1. Update version numbers in:
   • pyproject.toml
   • mcp_server_boilerplate/__init__.py
2. Clean previous builds:

3. Build and upload:

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