flask-mcp-server

Flask-based Model Context Protocol (MCP) server for Python. Drop it into any Flask app or run it standalone. Ships with security and ops features out of the box.

Spec target: MCP 2025-06-18 — Streamable HTTP transport with a unified /mcp endpoint (POST for JSON-RPC; GET for SSE). Back-compat routes retained.

Package version: 0.6.1

Requirements

Python 3.9+
Flask 3.x (auto-installed)

Install

From PyPI

pip install flask-mcp-server

Add to requirements.txt from a file path:

flask-mcp-server==0.6.1

Quick Start

Integrated into an existing Flask app (integrated HTTP):

from flask import Flask
from flask_mcp_server import mount_mcp, Mcp
from flask_mcp_server.http_integrated import mw_auth, mw_ratelimit, mw_cors

app = Flask(__name__)

@Mcp.tool(name="sum")
def sum_(a: int, b: int) -> int:
    return a + b

# Mount at /mcp with useful middlewares
mount_mcp(app, url_prefix="/mcp", middlewares=[mw_auth, mw_ratelimit, mw_cors])

if __name__ == "__main__":
    app.run(port=8765)

Dedicated server app (ships with docs endpoints):

flask-mcp serve-http
# Swagger: http://127.0.0.1:8765/swagger
# OpenAPI: /docs.json

STDIO transport:

flask-mcp serve-stdio

What’s new in 0.6.1

Unified MCP endpoint (/mcp):
- POST a single JSON-RPC message (request/notification/response). If the Accept header includes text/event-stream, the server streams the response via SSE; otherwise returns JSON.
- GET to open an SSE stream for server messages (optional). Supports Last-Event-ID for resumability in future minor releases.
Protocol header: Accepts MCP-Protocol-Version: 2025-06-18 (or 2025-03-26 for back-compat); others => 400 Bad Request.
Sessions (minimal): If the POSTed method is "initialize", response includes Mcp-Session-Id header. Clients can include this header on subsequent requests.
Origin validation: Optional FLASK_MCP_ALLOWED_ORIGINS (comma-separated). If set, only requests with matching Origin are allowed at the unified MCP endpoint.
Backwards compatibility: legacy endpoints /mcp/list, /mcp/call, /mcp/batch remain.

Configuration (env vars)

Auth & roles

export FLASK_MCP_AUTH_MODE=apikey     # none|apikey|hmac
export FLASK_MCP_API_KEYS="k1,k2"
export FLASK_MCP_API_KEYS_MAP="k1:admin|user;k2:user"   # per-key roles
export FLASK_MCP_HMAC_SECRET="supersecret"              # if using HMAC

Rate limiting

export FLASK_MCP_RATE_LIMIT=60/m      # format: <N>/<s|m|h|d>
export FLASK_MCP_RATE_SCOPE=key       # ip|key

CORS, Origins & Logging

export FLASK_MCP_ALLOWED_ORIGINS="http://localhost:3000,https://your.app"
export FLASK_MCP_CORS_ORIGIN="*"
export FLASK_MCP_LOG_FORMAT=json

Providers autoload

export FLASK_MCP_PROVIDERS="my_pkg.mcp_provider:Provider,another.mod:Provider"

Core Concepts

Registry — stores tools, resources, prompts, completions.
Decorators — @tool, @resource, @prompt, @completion_provider register elements.
Facade — Mcp.tool(...) etc. (fluent, same params as decorators).
Roles/ACL — per-element role lists checked at call time.
TTL cache — per-tool/resource memoization via ttl=int_seconds (memory backend).
Middleware — pluggable pipeline for integrated HTTP routes.
Service Providers — register(container, registry) and boot(app, registry) to wire services/routes.
Transports — Streamable HTTP unified endpoint, STDIO, and SSE notifications (hello + registry change).

Examples

A. Unified MCP endpoint usage

# List registry (JSON)
curl -s -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"mcp.list"}' | jq .

# Call a tool over SSE
curl -N -X POST http://127.0.0.1:8765/mcp \
  -H "Accept: text/event-stream, application/json" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"2","method":"mcp.call","params":{"kind":"tool","name":"sum","args":{"a":5,"b":7}}}'

B. Tools with roles & TTL cache

from flask_mcp_server import Mcp

@Mcp.tool(name="math.add", roles=["user","admin"], ttl=30)
def add(a: int, b: int) -> int:
    return a + b

C. Resources & ResourceTemplates

from flask_mcp_server import resource, ResourceTemplate

@resource(name="profile", ttl=15)
def profile(user_id: int) -> dict:
    return {"id": user_id, "name": "Alice"}

tpl = ResourceTemplate("https://api.example.com/items/{id}")
url = tpl.expand(id=42)  # "https://api.example.com/items/42"

D. Prompts & Completions

from flask_mcp_server import prompt, completion_provider
from typing import List

@prompt(name="greet")
def greet(name: str) -> str:
    return f"Write a warm one-line greeting for {name}."

@completion_provider(name="cities")
def cities(prefix: str="") -> List[str]:
    base = ["Dhaka","Chittagong","Khulna","Rajshahi"]
    return [c for c in base if c.lower().startswith(prefix.lower())]

E. Batch Calls (compat)

curl -s -X POST http://127.0.0.1:8765/mcp/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"kind":"tool","name":"math.add","args":{"a":1,"b":2}},
    {"kind":"prompt","name":"greet","args":{"name":"Bashar"}}
  ]' | jq .

F. SSE (hello + registry events)

# GET /mcp opens an SSE stream and emits a hello event and future registry change events.
curl -N http://127.0.0.1:8765/mcp

G. Auth: API keys & HMAC

export FLASK_MCP_AUTH_MODE=apikey
export FLASK_MCP_API_KEYS="secret123"
curl -s http://127.0.0.1:8765/mcp/list -H "X-API-Key: secret123"

# HMAC
python - <<'PY'
import hmac, hashlib, json, requests
secret = b"supersecret"
body = json.dumps({"jsonrpc":"2.0","id":1,"method":"mcp.list"}).encode()
sig = hmac.new(secret, body, hashlib.sha256).hexdigest()
print(requests.post("http://127.0.0.1:8765/mcp",
    headers={"X-Signature":"sha256="+sig,"Content-Type":"application/json"},
    data=body).text)
PY

H. Rate limiting

export FLASK_MCP_RATE_LIMIT=100/m
export FLASK_MCP_RATE_SCOPE=key      # or 'ip'

I. Service Providers

# my_pkg/mcp_provider.py
from flask_mcp_server import ServiceProvider, Mcp

class Provider(ServiceProvider):
    def register(self, container, registry):
        @Mcp.tool(name="time.now")
        def now() -> str:
            import time; return str(int(time.time()))

J. Discovery (auto-register)

# Suppose your tools live in package 'my_tools'
python -c "from flask_mcp_server.discovery import discover_package; discover_package('my_tools')"

K. CLI

flask-mcp serve-http      # unified /mcp endpoint
flask-mcp serve-stdio     # stdio transport
flask-mcp list            # print registry

L. OpenAPI & Swagger

/docs.json — OpenAPI 3.1 JSON
/swagger — Swagger UI

FAQ

Is Redis required? No. 0.6.1 uses in-memory backends by default.

Can I mount it into any Flask project? Yes—mount_mcp(app, url_prefix="/mcp").

Does it fully implement all MCP JSON-RPC methods? It implements the transport semantics and common operations (mcp.list, mcp.call, compat endpoints). If you need additional method names or shapes to match a specific client, open an issue or extend in a Service Provider.

Troubleshooting

400 unsupported_protocol_version — set MCP-Protocol-Version: 2025-06-18.
403 origin_not_allowed — configure FLASK_MCP_ALLOWED_ORIGINS or remove it.
401 invalid_api_key / invalid_signature — check headers and env vars.
429 rate_limited — adjust FLASK_MCP_RATE_LIMIT or scope.

Contributing

We welcome contributions to flask-mcp-server! Whether it's bug fixes, new features, improved documentation, or ideas—you're invited to collaborate.

Getting Started

Fork this repository and clone it locally.

Set up a virtual environment and install the package in editable mode:

python -m venv .venv && source .venv/bin/activate
pip install -e .[dev,redis,async]

Run the test suite:
```
pytest
```
Create a new branch for your contribution:

git checkout -b my-feature-branch

Make your changes and commit:

git commit -m "Add: description of the change"

Push your branch and open a Pull Request (PR) on GitHub.

Contribution Guidelines

Follow consistent code style (Black, PEP8).
Write or update tests for any new logic.
Keep commits focused and descriptive.
Document any new features in the README if needed.
Open an issue if you'd like to discuss a large idea before coding.

Feedback & Issues

Use the GitHub Issues page to report bugs, request features, or ask questions.

We appreciate every contribution, big or small. Thank you for helping improve flask-mcp-server!

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
examples		examples
src/flask_mcp_server		src/flask_mcp_server
tests		tests
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini

bashar94/flask-mcp-server

Folders and files

Latest commit

History

Repository files navigation