MCP Server Boilerplate

A minimal, extensible template for building Python-based MCP (Model-Context Protocol) servers. This repository provides a small, well-documented starting point that demonstrates common patterns for transport selection, tool registration, configuration, and VS Code integration.

Overview

This boilerplate implements:

• A simple MCP server entrypoint (mcp_server.py)
• Pluggable transports (STDIO and SSE) selectable via mcp_settings.py
• A transport configurator that can generate a .vscode/mcp.json entry
• A clear place to add MCP tools (commands) and helper modules

The goal is to make it easy to prototype and ship MCP servers that integrate with tooling and editors while keeping the code small and approachable.

Features

• Example STDIO and SSE transports with configuration
• Automated VS Code server configuration (mcp_transport_configurator.py)
• Virtual-environment friendly startup and PYTHONPATH support
• Lightweight structure for adding MCP tools and utilities

File Structure

├── mcp_server.py
├── mcp_settings.py
├── mcp_setup_env.py
├── mcp_transport_configurator.py
├── mcp_utils.py
├── requirements.txt
├── README.md
└── tools/               # place to add reusable helper modules

Customize the layout as your project grows — add src/, tests/, or split tools into packages.

Setup

1. Create and activate a virtual environment (recommended):

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS/Linux
   source .venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. (Optional) Run the environment helper to set a project env var used by the configurator:

   python mcp_setup_env.py
   

Configuration

Edit mcp_settings.py to choose transport protocol and other runtime options:

• PROTOCOL — set to STDIO (default) or SSE
• PORT — used only for SSE mode
• MCP_NAME — logical name used by the transport configurator

Running the Server

Start the server directly:

python mcp_server.py

Or only update the editor/server configuration without starting:

python mcp_transport_configurator.py

VS Code Integration

The included configurator writes a .vscode/mcp.json entry that can be used by editor extensions to launch the MCP server in STDIO mode or connect via SSE.

Development Notes

• Prefer keeping requirements.txt or migrate to pyproject.toml + lockfile for modern dependency management.
• Add unit tests under tests/ and run them with your preferred test runner.
• Keep tools small and focused; register MCP commands from a single initialization point.

Contributing

Contributions are welcome. Open issues or pull requests for bug fixes, documentation improvements, or new example tools demonstrating MCP patterns.

License

See the LICENSE file for licensing details.

Author

Provided as an MCP server boilerplate.