FastAPI-MCP

0.4.0 verified Tue May 12 auth: no python install: verified

FastAPI-MCP is a Python library that automatically converts FastAPI endpoints into Model Context Protocol (MCP) tools, enabling seamless integration with Large Language Models (LLMs) and AI agents. It provides a straightforward way to expose existing FastAPI APIs as discoverable and callable tools for AI. The library is currently at version 0.4.0 and maintains an active release cadence with frequent updates and feature additions.

pip install fastapi-mcp uvicorn

Common errors

error ModuleNotFoundError: No module named 'fastapi_mcp' ↓

cause The `fastapi-mcp` library is not installed in your active Python environment, or there is a typo in the import statement.

fix

Install the library using pip install fastapi-mcp or uv add fastapi-mcp. Ensure your import statement is from fastapi_mcp import FastApiMCP.

error TypeError: FastApiMCP.__init__() got an unexpected keyword argument 'base_url' ↓

cause The `base_url` parameter was removed or changed in recent versions of `fastapi-mcp`, and older code or documentation is being followed.

fix

Remove the base_url argument from the FastApiMCP constructor, as it is often automatically determined or no longer required.

error RecursionError: maximum recursion depth exceeded ↓

cause This error typically occurs when `fastapi-mcp` attempts to resolve OpenAPI schemas for FastAPI applications that use recursive Pydantic models, creating circular `$ref` references that the schema resolution logic doesn't handle gracefully.

fix

Implement a try-except RecursionError block around your FastApiMCP initialization and mounting to handle this gracefully, or restructure your Pydantic models to avoid direct recursion if possible.

error AttributeError: 'JSONRPCMessage' object has no attribute 'message' ↓

cause This issue arises from an incompatibility between `fastapi-mcp` and specific versions of the underlying `mcp` Python SDK, particularly when `mcp` version 1.8.0 is installed.

fix

Downgrade the mcp package to a compatible version, for example, pip install mcp==1.7.0.

Warnings

breaking The `mount()` method is deprecated as of v0.4.0 and will be removed in future versions. It previously handled SSE transport by default. ↓

fix Use `mcp.mount_http()` for HTTP transport (recommended) or `mcp.mount_sse()` for Server-Sent Events (SSE) transport instead.

breaking The `base_url` argument was removed from the `FastApiMCP` constructor. It is now redundant due to the default use of ASGI transport. ↓

fix Remove the `base_url` argument when initializing `FastApiMCP`. If an explicit base URL is required, configure it via the `http_client` argument with your own `httpx.AsyncClient`.

breaking Version 0.2.0 introduced a complete refactor from a function-based API to a new class-based `FastApiMCP` API. This changed how MCP instances are created and mounted. ↓

fix Migrate your code to use the `FastApiMCP` class (e.g., `mcp = FastApiMCP(app)` followed by `mcp.mount()`, or `mcp.mount_http()`/`mcp.mount_sse()` in later versions).

gotcha FastAPI-MCP uses the `operation_id` from your FastAPI routes as the MCP tool names. If `operation_id` is not explicitly provided, FastAPI auto-generates a cryptic one. ↓

fix Always provide an explicit `operation_id` parameter to your FastAPI route definitions (`@app.get('/path', operation_id='my_tool_name')`) for clearer and more intuitive tool names for AI agents.

gotcha FastAPI-MCP depends on the `mcp` package. Breaking changes in the `mcp` SDK itself (e.g., `mcp` SDK 1.8.0) can cause issues with `fastapi-mcp` if not explicitly handled. ↓

fix Ensure your `mcp` dependency is compatible with your `fastapi-mcp` version. Refer to `fastapi-mcp` release notes for required `mcp` versions (e.g., v0.3.4 fixed an issue by upgrading `mcp` to 1.8.1).

breaking `fastapi-mcp` requires Python >= 3.10. Installation will fail on older Python versions. ↓

fix Upgrade your Python environment to 3.10 or newer to install `fastapi-mcp`.

Install

uv add fastapi-mcp uvicorn

Install compatibility verified last tested: 2026-05-12 v0.4.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 2.56s 74.0M 32.5M noisy

3.10 alpine (musl) - - 2.56s 72.7M 32.5M -

3.10 slim (glibc) wheel 9.0s 1.93s 73M 32.5M noisy

3.10 slim (glibc) - - 2.04s 72M 32.5M -

3.11 alpine (musl) wheel - 2.95s 81.2M 34.4M noisy

3.11 alpine (musl) - - 3.33s 79.9M 34.4M -

3.11 slim (glibc) wheel 8.0s 2.72s 80M 34.4M noisy

3.11 slim (glibc) - - 2.75s 79M 34.4M -

3.12 alpine (musl) wheel - 2.63s 72.0M 34.1M noisy

3.12 alpine (musl) - - 2.98s 70.7M 34.1M -

3.12 slim (glibc) wheel 6.8s 2.70s 71M 34.1M noisy

3.12 slim (glibc) - - 2.95s 70M 34.1M -

3.13 alpine (musl) wheel - 2.57s 71.9M 34.7M noisy

3.13 alpine (musl) - - 2.92s 70.5M 34.7M -

3.13 slim (glibc) wheel 6.7s 2.60s 71M 34.7M noisy

3.13 slim (glibc) - - 2.99s 70M 34.7M -

3.9 alpine (musl) build_error - - - - - -

3.9 alpine (musl) - - - - - -

3.9 slim (glibc) build_error - 1.6s - - - -

3.9 slim (glibc) - - - - - -

Imports

FastApiMCP
wrong
```
from fastmcp import FastApiMCP
```
correct
```
from fastapi_mcp import FastApiMCP
```
Ensure you import from `fastapi_mcp` for the FastAPI integration, not the generic `fastmcp` SDK.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to create a basic FastAPI application, instantiate `FastApiMCP` with your app, and then mount the MCP server using the recommended `mount_http()` method. The `operation_id` is explicitly set for clarity in the exposed MCP tool. To run, save as `main.py` and execute `python main.py`. The MCP server will be available at `http://localhost:8000/mcp`.

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Create a FastAPI app
app = FastAPI(title="My MCP API")

@app.get("/hello")
def read_root():
    return {"message": "Hello, World!"}

@app.get("/items/{item_id}", operation_id="get_item_by_id")
def read_item(item_id: int):
    """Get a specific item by its ID"""
    return {"item_id": item_id, "name": f"Item {item_id}"}

# Create an MCP server based on this app
mcp = FastApiMCP(app)

# Mount the MCP server to your app using the recommended HTTP transport
mcp.mount_http()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)