Skip to main content
Glama
MCP Boilerplate Server

MCP Boilerplate Server

by shazaaly

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

Related MCP server: ddg--mcp5

Quick Start

Prerequisites

  • Python 3.12 or higher

  • uv (recommended) or pip

Installation Options

# 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
  1. 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"
  1. Install dependencies:

uv sync

Alternative with pip:

pip install fastmcp>=2.11.3
  1. 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
  1. 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
  1. Create PyPI account at pypi.org

  2. 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
  1. Test upload to TestPyPI (recommended first time):

uv run twine upload --repository testpypi dist/*
  1. 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/
  1. 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

Available Tools

4 tools
addB

Add two numbers together

Inputs: a (required), b (required). Returns: result

get_user_infoB

Get user information by ID

Inputs: user_id (required). Returns: object

greetB

Greet a person by name

Inputs: name (required). Returns: result

multiplyB

Multiply two numbers together

Inputs: a (required), b (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 4 tools

    Disambiguation2/5

    The tools have unclear boundaries and overlapping purposes. 'add' and 'multiply' are distinct mathematical operations, but 'get_user_info' and 'greet' are unrelated to them and to each other, creating a confusing mix of domains. An agent might struggle to choose between tools for different tasks due to the lack of a cohesive theme.

    Naming Consistency2/5

    The naming is inconsistent with mixed conventions. 'add' and 'multiply' use simple verb forms, while 'get_user_info' follows a verb_noun pattern and 'greet' is a standalone verb. This lack of a predictable pattern makes the tool set harder to navigate and understand.

    Tool Count3/5

    With 4 tools, the count is borderline appropriate. It feels thin for a general-purpose server, as it lacks depth in any single domain (e.g., math or user management). However, it's not extreme, so it's reasonable but could benefit from more focused scope.

    Completeness2/5

    There are significant gaps in the tool surface for any inferred domain. If the domain is math, tools like subtract or divide are missing; if it's user management, tools for creating or updating users are absent. The set is incomplete, leading to potential agent failures when trying to perform common operations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A basic MCP server template built with FastMCP framework that provides example tools for echoing messages and retrieving server information. Serves as a starting point for building custom MCP servers with both stdio and HTTP transport support.
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A basic MCP server template with example tools including message echo and server information retrieval. Built with FastMCP framework and supports both stdio and HTTP transports.
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A basic MCP server template with example tools for echoing messages and retrieving server information. Built with FastMCP framework and supports both stdio and HTTP transports for integration with various clients.
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A basic MCP server template with example tools for echoing messages and retrieving server information. Built with FastMCP framework and supports both stdio and HTTP transports.
      -