Skip to main content
Glama
Sign In
MCP server Python starter

MCP server Python starter

by opikdev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP server Python starter

A production-ready Model Context Protocol server in Python, ready to customize with coding agents. It runs over stdio for local clients and Streamable HTTP for remote ones, with OAuth, tests through real MCP clients, and a release pipeline.

CI License: MIT

Features

  • Current protocol: built on the official MCP Python SDK v2 and its MCPServer API, for the 2026-07-28 spec, while still serving older clients.

  • Two transports: stdio for Claude Code, Claude Desktop, and Cursor, plus stateless Streamable HTTP that scales horizontally.

  • Secure HTTP: OAuth per the MCP authorization spec, or static tokens. It won't start without an auth mode, and it blocks DNS rebinding.

  • Typed tools: get_time, search_docs, and whoami use type hints and Pydantic models as their schemas, with annotations and readable errors, plus docs:// resources.

  • Backend integration: list_notes and create_note call a REST API with timeouts, validated responses, and errors the model can act on. See Connect a backend API.

  • Real tests: tools are tested through real MCP clients in process, over stdio, and over HTTP, on both protocol eras, plus the built wheel and the Docker image.

  • Strict gates: Ruff, mypy in strict mode, and 90% coverage.

  • Publishing: releases to PyPI, the MCP Registry, and GHCR, with a test that keeps server.json and pyproject.toml in step.

  • Agent-ready: AGENTS.md, skills, and checks that run on every commit.

Related MCP server: mcp-agent-kit

Quick start

You need uv, which installs Python 3.15 for you, and Node for the MCP Inspector:

git clone https://github.com/opikdev/mcp-server-python-starter
cd mcp-server-python-starter
make sync
make inspect

The MCP Inspector opens in your browser. Connect, list the tools, and call get_time.

To run it over HTTP in Docker instead:

docker compose up --build --wait mcp

The server is now at http://localhost:3000/mcp, with the dev token dev-token-change-me-0123. To connect Claude Code, Claude Desktop, Cursor, or VS Code, see Connect a client.

Usage

Task

Command

Try the tools in the MCP Inspector

make inspect

Serve over HTTP on your machine

cp .env.example .env, then make dev

Run lint, types, tests with coverage, and repo checks

make verify

Test the built wheel, the Docker image, and a real backend

make e2e

Fix formatting and lint you can fix automatically

make format

make e2e needs Docker. Over HTTP, the server needs an auth mode. See Configure HTTP auth.

To add a tool, create a module in src/mcp_app/tools/ with a register_* function, call it from src/mcp_app/server.py, and test it in tests/integration/test_tools.py. Before you release, read Publish a release.

Project structure

Path

Purpose

src/mcp_app/cli.py

Entry point: stdio by default, or HTTP with --http

src/mcp_app/server.py

Builds the server with every tool and resource

src/mcp_app/tools/

One module per tool, or a small related set

src/mcp_app/resources/

docs:// resources

src/mcp_app/http.py, src/mcp_app/auth/

The HTTP app, health check, and token verifiers

src/mcp_app/upstream/

Clients for backend APIs

tests/

Unit, integration, and end-to-end tests

server.json

MCP Registry metadata

docs/

Architecture, guides, and decisions

Contributing

Read CONTRIBUTING.md before opening a pull request, and follow the code of conduct.

Security

Report vulnerabilities privately, as described in SECURITY.md.

License

Released under the MIT License.

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • Graft

    schrepa
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables building agent-ready APIs that expose tools as both HTTP and MCP endpoints from a single server definition, with automatic OpenAPI, discovery docs, and interactive API reference.
    5
    Apache 2.0

  • mcp-agent-kit

    hummbl-dev
    A
    license
    A
    quality
    B
    maintenance
    Enables building and running zero-dependency MCP servers with automatic JSON Schema generation, exposing Python tools to Claude Desktop, Cursor, and autonomous agent fleets.
    2
    Apache 2.0

  • McpHub

    John0King
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI tools to uniformly discover, inspect, and call tools, prompts, and resources from multiple upstream MCP servers through a small set of fixed MCP tools, over stdio or HTTP.
    2
    MIT

  • Slipway

    thenavidm
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables developers to expose a single set of tool definitions as MCP server tools over stdio or Streamable HTTP, so Claude Code, Codex, Claude Desktop and Cursor can call them with risk-based annotations, human-approved irreversible writes, typed structured results and long-running job handling built in. It also ships the same tools as a CLI from one source, keeping both surfaces in parity.
    594 npm
    Apache 2.0