MCP Server Template

A local MCP server template for building Claude integrations. Runs locally via stdio transport — all tokens and credentials stay on your machine.

Prerequisites

• Python 3.12+
• uv for dependency management

Quick Start

# Clone the repo
git clone https://github.com/stevesimpson418/mcp-repo-template.git
cd mcp-server-template

# Install dependencies (creates .venv/ in the project directory)
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your API credentials

New to uv? uv sync reads pyproject.toml, creates a .venv/ virtualenv inside the project folder, and installs all dependencies into it. You don't need to activate it — uv run <command> handles that automatically.

Adding to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Tip: Run uv run which python from the project directory to get the exact path for command.

{
  "mcpServers": {
    "my-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_server_template.server"],
      "env": {
        "API_TOKEN": "your_token_here"
      }
    }
  }
}

Adding to Claude Code CLI

Use the claude mcp add command to register the server. This works from any directory.

claude mcp add --scope user my-server \
  --transport stdio \
  --env API_TOKEN=your_token_here \
  -- /path/to/my-server/.venv/bin/python -m mcp_server_template.server

Replace /path/to/my-server with the actual path where you cloned the repo.

Tip: Run uv run which python from the project directory to get the exact .venv/bin/python path for the command.

The --scope user flag saves to ~/.claude.json so the server is available across all projects. Without it, the command defaults to local scope (tied to whatever directory you run it from). To scope it to a single project instead, use --scope project which writes to .mcp.json in the project root.

To verify the server is registered:

claude mcp list

Restart Claude Code after adding. The tools should appear in the /mcp menu.

Note: Claude Code CLI uses a different configuration from Claude Desktop. The claude mcp add command is the recommended way to register MCP servers — do not add them to ~/.claude/settings.json as that file is used for permissions and hooks only.

Available Tools

Usage Examples

Verify the server is working:

hello()              → "Hello, World!"
hello(name="Alice")  → "Hello, Alice!"

Once you add your own tools, replace these examples with 2–3 realistic workflows showing how the tools compose together. See the gmail-mcp-server README for a good model.

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=mcp_server_template --cov-report=term-missing

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Install git hooks
lefthook install

Local .env file

When running the server manually outside Claude Desktop/Code (e.g., for development or debugging), you can create a .env file in the project root so the server picks up config without passing environment variables:

API_TOKEN=your_token_here

This is only needed for local development. The Claude Desktop and Claude Code CLI configs pass these values directly via the env block.

Releases

This project uses release-please for automated versioning and releases. The version is determined by Conventional Commits:

• fix: commits bump the patch version (e.g. 0.1.0 → 0.1.1)
• feat: commits bump the minor version (e.g. 0.1.1 → 0.2.0)
• BREAKING CHANGE in the commit footer bumps the major version

When commits land on main, release-please opens (or updates) a Release PR that:

• Bumps the version in pyproject.toml
• Updates CHANGELOG.md with grouped entries

Merging the Release PR creates a git tag and GitHub Release automatically.

Bootstrapping a New Project

Use bootstrap.sh to create a new MCP server from this template:

./bootstrap.sh my-service my_service_package your-github-user "Your Name"

This renames all placeholders (package name, badges, LICENSE copyright), updates configs, and gets you ready to code.

Packaging & Distribution

This server is currently distributed as source via git. To install:

git clone https://github.com/stevesimpson418/mcp-repo-template.git
cd mcp-server-template
uv sync

This is the standard distribution model for local-stdio MCP servers today. The project is already configured for wheel builds via hatchling, so future distribution options include:

• PyPI — publish to PyPI, then install with uv tool install <your-package> or pip install <your-package>. Would require adding a publish workflow to CI.
• uvx — once on PyPI, uvx <your-package> runs the server without cloning the repo. Claude Desktop/Code config would point to the uvx-managed binary instead of a local .venv.

License

MIT