Skip to content
Public template

About

🏡️ MCP Server with CLI interface ready for distribution

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

558 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

mcp-template

2

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

Deploy on Railway Β  Deploy to Render

Project Version Python Version GitHub repo size GitHub Actions Workflow Status skills.sh


Agent Prompt

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-Template

The 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).

App Distribution

  • 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

Key Features

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

Architecture

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)β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

MCP UI (optional)

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.

Quick Start

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 / dev

Deploy

One-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.

CLI Usage

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 output

Adding Commands

Drop 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 migrate

Or scaffold with: uv run mymcp init my_command --desc "Does something".

Configuration

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_KEY

CLI 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 override

Full configuration docs

Credits

This software uses the following tools:

About the Core Contributors

Made with contrib.rocks.

About

🏡️ MCP Server with CLI interface ready for distribution

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages