Batteries-included Python template. One codebase ships as a CLI, an MCP server, and an HTTP API over a shared service registry.
Key Features β’ Architecture β’ Quick Start β’ CLI Usage β’ Adding Commands β’ Configuration β’ Deploy β’ Credits
Copy and paste this into your AI coding agent (Claude Code, Cursor, Copilot, etc.) to install:
Install the CLI and download the gmail-mcp skill:
pip install mcp-template
curl -fsSL https://raw.githubusercontent.com/Miyamura80/MCP-Template/main/scripts/install-skills.sh -o install-skills.sh
bash install-skills.sh && rm install-skills.sh
The official gmail-mcp agent skill is self-published on skills.sh. Install it directly with:
npx skills add Miyamura80/MCP-TemplateThe skill's source of truth lives in skills/gmail-mcp/SKILL.md;
make sync-skills mirrors it to the landing page's
/.well-known/agent-skills/ discovery tree (digest-pinned in index.json).
- MCP server with OAuth
- Claude connectors and ChatGPT apps
- APIs and SDKs
- Chat interfaces like iMessage and WhatsApp
- A dashboard that uses the same MCP layer
- Open source
| Feature | Stack |
|---|---|
| CLI (auto-discovery commands, global flags, shell completions, self-update) | Typer |
MCP server (streamable HTTP at /mcp, services auto-registered as tools; stdio supported for local dev) |
FastMCP |
HTTP API server (also hosts /mcp) |
FastAPI + Uvicorn |
| Auth | WorkOS + API keys |
| Payments | Stripe subscriptions + x402 sell-side paywall (price a tool with @service(price=...); agents pay per call in stablecoins, Cloudflare Wallets / x402 ecosystem) |
| Database + migrations | SQLAlchemy + Alembic |
Config (YAML + .env) |
Pydantic-settings |
| LLM inference + observability | DSPY + LiteLLM + LangFuse |
| Testing | pytest + TestTemplate |
| Lint / type / dead-code | Ruff + Vulture + ty + import-linter |
| Pre-commit (folder size, ai-writing, agent-config sync) | prek |
| Telemetry | Anonymous, opt-out |
One codebase, three interfaces. Write business logic once in services/ and it ships as a CLI subcommand, an MCP tool, and an HTTP route - same Pydantic input/output contract everywhere.
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β src/cli/app β β mcp_server/ β β api_server/ β transport / interface
β (Typer) β β (FastMCP) β β (FastAPI) β
ββββββββ¬ββββββββ ββββββββ¬ββββββββ ββββββββ¬ββββββββ
β β β
βββββββββββββββββββΌββββββββββββββββββ
βΌ
βββββββββββββββββ
β services/ β pure @service functions
β @service β (transport-agnostic)
βββββββββ¬ββββββββ
βΌ
βββββββββββββββββ
β models/ β Pydantic I/O contracts
βββββββββ¬ββββββββ
βΌ
ββββββββββββββ¬ββββββββ¬βββββββββββββ¬ββββββββββββββ
β common/ β db/ β utils/llm/ β src/utils/ β shared infra
β (config) β (ORM) β (DSPY) β (logs/theme)β
ββββββββββββββ΄ββββββββ΄βββββββββββββ΄ββββββββββββββ
Need elicitation, image output, or an iframe dashboard for an MCP tool? Add an opt-in enhancer in mcp_server/enhancers/. Enhancers wrap a service for the MCP transport only - the pure service stays untouched and CLI/API consumers are unaffected.
See mcp_server/MCP_UI_ARCHITECTURE.md for the full design.
make onboard # interactive setup (rename, deps, env, hooks)
uv sync # install deps
uv run mymcp --help # see all CLI commands
uv run mymcp greet Alice # run a command
uv run mymcp init my_command # scaffold a new command
uv run mymcp-serve # start the server (HTTP API + MCP at /mcp on one port)
uv run mymcp-mcp # legacy: stdio MCP only, for local Claude Desktop / devOne-click deploy to Railway or Render (backend + managed Postgres, migrations run automatically). See deployment docs for the per-platform setup, the Railway template variable map, and OAuth/secret wiring.
Global flags go before the subcommand:
| Flag | Short | Description |
|---|---|---|
--verbose |
-v |
Increase output verbosity |
--quiet |
-q |
Suppress non-essential output |
--debug |
Show full tracebacks on error | |
--format |
-f |
Output format: table, json, plain |
--dry-run |
Preview actions without executing | |
--version |
-V |
Print version and exit |
uv run mymcp --format json config show # JSON output
uv run mymcp --dry-run greet Bob # preview without executing
uv run mymcp --verbose greet Alice # detailed outputDrop a Python file in src/cli/commands/ and it is auto-discovered.
Single command - export a main() function:
# src/cli/commands/hello.py
from typing import Annotated
import typer
def main(name: Annotated[str, typer.Argument(help="Who to greet.")]) -> None:
"""Say hello."""
typer.echo(f"Hello, {name}!")uv run mymcp hello World # Hello, World!Subcommand group - export app = typer.Typer():
# src/cli/commands/db.py
import typer
app = typer.Typer()
@app.command()
def migrate() -> None:
"""Run migrations."""
...uv run mymcp db migrateOr scaffold with: uv run mymcp init my_command --desc "Does something".
from common import global_config
# Access config values from common/global_config.yaml
global_config.example_parent.example_child
# Access secrets from .env
global_config.OPENAI_API_KEYCLI config inspection:
uv run mymcp config show # full config
uv run mymcp config get llm_config.cache_enabled # single value
uv run mymcp config set logging.verbose false # write overrideThis software uses the following tools:
- Cursor: The AI Code Editor
- uv
- Typer: CLI framework
- Rich: Terminal formatting
- prek: Rust-based pre-commit framework
- DSPY: Pytorch for LLM Inference
- LangFuse: LLM Observability Tool
Made with contrib.rocks.
