Skip to content

Commit 3c8da6a

Browse files
itay-tadataitay-tadata
committed
first commit
0 parents  commit 3c8da6a

File tree

15 files changed

+2204
-0
lines changed

15 files changed

+2204
-0
lines changed

‎INSTALL.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Installation Guide
2+
3+
This guide will help you install and set up FastAPI-MCP on your system.
4+
5+
## Prerequisites
6+
7+
- Python 3.10 or higher
8+
- pip (Python package installer)
9+
10+
## Installation from PyPI
11+
12+
The simplest way to install FastAPI-MCP is directly from PyPI:
13+
14+
```bash
15+
pip install fastapi-mcp
16+
```
17+
18+
## Installation from Source
19+
20+
You can also install FastAPI-MCP from source:
21+
22+
```bash
23+
# Clone the repository
24+
git clone https://github.com/yourusername/fastapi-mcp.git
25+
cd fastapi-mcp
26+
27+
# Install the package
28+
pip install -e .
29+
```
30+
31+
## Verifying Installation
32+
33+
To verify that FastAPI-MCP is installed correctly, run:
34+
35+
```bash
36+
fastapi-mcp --help
37+
```
38+
39+
You should see the help message for the FastAPI-MCP CLI.
40+
41+
## Installing Development Dependencies
42+
43+
If you want to contribute to FastAPI-MCP or run the tests, you can install the development dependencies:
44+
45+
```bash
46+
pip install -e ".[dev]"
47+
```
48+
49+
## Running Tests
50+
51+
To run the tests, make sure you have installed the development dependencies, then run:
52+
53+
```bash
54+
pytest
55+
```

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 FastAPI-MCP Team
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# FastAPI-MCP
2+
3+
A magical, zero-configuration tool for generating Model Context Protocol (MCP) servers from FastAPI applications.
4+
5+
## Features
6+
7+
- **Automatic discovery** of all FastAPI endpoints in your application
8+
- **Zero configuration** required - just point it at your FastAPI app and it works
9+
- **CLI tool** for easy generation and execution of MCP servers
10+
- **Stdio support** for MCP protocol communication
11+
- **Type-safe conversion** from FastAPI endpoints to MCP tools
12+
- **Documentation preservation** from FastAPI to MCP
13+
- **Claude integration** for easy installation and use with Claude desktop application
14+
- **API Integration** - automatically makes HTTP requests to your FastAPI endpoints
15+
16+
## Installation
17+
18+
```bash
19+
pip install fastapi-mcp
20+
```
21+
22+
For detailed installation instructions, see [INSTALL.md](INSTALL.md).
23+
24+
## Usage
25+
26+
### Generate an MCP server from a FastAPI app
27+
28+
```bash
29+
# Point to a FastAPI application file or module
30+
fastapi-mcp generate app.py
31+
32+
# Or specify the app variable if it's not named 'app'
33+
fastapi-mcp generate module.py:my_app
34+
35+
# Use a custom base URL for the API endpoints (default: http://localhost:8000)
36+
fastapi-mcp generate app.py --base-url https://api.example.com
37+
```
38+
39+
### Preview the generated MCP server
40+
41+
```bash
42+
fastapi-mcp preview
43+
```
44+
45+
### Run the generated MCP server
46+
47+
```bash
48+
fastapi-mcp run
49+
```
50+
51+
### Install the server for Claude
52+
53+
```bash
54+
fastapi-mcp install
55+
```
56+
57+
## How It Works
58+
59+
FastAPI-MCP automatically:
60+
61+
1. Discovers all FastAPI endpoints in your application
62+
2. Converts route handlers to MCP tools
63+
3. Maps request/response models to MCP schemas
64+
4. Preserves documentation and type information
65+
5. Generates a standalone MCP server that uses the official MCP Python SDK
66+
6. **Makes actual HTTP requests** to the underlying FastAPI endpoints
67+
68+
## Example
69+
70+
Original FastAPI code:
71+
72+
```python
73+
from fastapi import FastAPI
74+
from pydantic import BaseModel
75+
76+
app = FastAPI()
77+
78+
class Item(BaseModel):
79+
name: str
80+
price: float
81+
is_offer: bool = None
82+
83+
@app.get("/items/{item_id}")
84+
def read_item(item_id: int, q: str = None):
85+
"""Get details for a specific item"""
86+
return {"item_id": item_id, "q": q}
87+
88+
@app.put("/items/{item_id}")
89+
def update_item(item_id: int, item: Item):
90+
"""Update an item with new information"""
91+
return {"item_id": item_id, "item": item}
92+
```
93+
94+
Generated MCP server:
95+
96+
```python
97+
# Generated MCP server
98+
# Original FastAPI app: FastAPI
99+
100+
from mcp.server import FastMCP
101+
import json
102+
import requests
103+
from typing import Dict, List, Optional, Union, Any
104+
try:
105+
from pydantic import BaseModel
106+
except ImportError:
107+
from pydantic.main import BaseModel
108+
109+
class Item(BaseModel):
110+
name: str
111+
price: float
112+
is_offer: Optional[bool] = None
113+
114+
# Original handler: __main__.read_item
115+
# Original handler: __main__.update_item
116+
117+
mcp = FastMCP("FastAPI")
118+
119+
@mcp.tool()
120+
async def read_item(item_id: int, q: str = None) -> Any:
121+
"""Get details for a specific item
122+
123+
Original route: GET /items/{item_id}
124+
"""
125+
# Original handler: __main__.read_item
126+
url = f'http://localhost:8000/items/{item_id}'
127+
params = {}
128+
if q is not None:
129+
params['q'] = q
130+
response = requests.get(url, params=params)
131+
response.raise_for_status()
132+
return response.json()
133+
134+
@mcp.tool()
135+
async def update_item(item_id: int, name: str, price: float, is_offer: bool = None) -> Any:
136+
"""Update an item with new information
137+
138+
Original route: PUT /items/{item_id}
139+
"""
140+
# Original handler: __main__.update_item
141+
url = f'http://localhost:8000/items/{item_id}'
142+
item = Item(**{"name": name, "price": price, "is_offer": is_offer})
143+
json_data = item.dict()
144+
response = requests.put(url, json=json_data)
145+
response.raise_for_status()
146+
return response.json()
147+
148+
if __name__ == "__main__":
149+
# Run the MCP server
150+
mcp.run()
151+
```
152+
153+
## Integration with FastAPI
154+
155+
The generated MCP server makes HTTP requests to your actual FastAPI server, which must be running separately. You can:
156+
157+
1. Run your FastAPI application normally (e.g., with `uvicorn app:app`)
158+
2. Generate the MCP server with a base URL pointing to your running FastAPI server
159+
3. Run the MCP server separately to provide MCP tools for LLMs
160+
161+
If your API requires authentication, you can customize the generated server code to include the necessary headers or tokens.
162+
163+
## Using with Claude
164+
165+
FastAPI-MCP makes it easy to use your API endpoints with Claude:
166+
167+
1. Generate an MCP server from your FastAPI app
168+
2. Install the server: `fastapi-mcp install`
169+
3. Open Claude desktop app
170+
4. Your API endpoints will be available as tools to Claude
171+
172+
## Examples
173+
174+
For more examples, see the [examples](examples) directory.
175+
176+
## Requirements
177+
178+
- Python 3.10+
179+
- FastAPI 0.100.0+
180+
- Pydantic 2.0.0+
181+
- mcp 1.3.0+
182+
- requests 2.25.0+
183+
184+
## Contributing
185+
186+
Contributions are welcome! Please feel free to submit a pull request.
187+
188+
## License
189+
190+
MIT

‎examples/README.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# FastAPI-MCP Examples
2+
3+
This directory contains examples of using FastAPI-MCP to generate MCP servers from FastAPI applications.
4+
5+
## Sample App
6+
7+
The `sample_app.py` file contains a simple FastAPI application with CRUD operations for an "Item" resource.
8+
9+
To run the FastAPI application:
10+
11+
```bash
12+
python sample_app.py
13+
```
14+
15+
To generate an MCP server from the sample app:
16+
17+
```bash
18+
cd .. # Go to the root directory
19+
python -m fastapi_mcp generate examples/sample_app.py
20+
```
21+
22+
This will create a `mcp_server` directory with the generated MCP server.
23+
24+
To preview the generated MCP server:
25+
26+
```bash
27+
python -m fastapi_mcp preview
28+
```
29+
30+
To run the generated MCP server:
31+
32+
```bash
33+
python -m fastapi_mcp run
34+
```
35+
36+
## How It Works
37+
38+
1. FastAPI-MCP discovers all endpoints in the FastAPI application
39+
2. It converts the endpoints to MCP tools
40+
3. It generates a standalone MCP server
41+
4. It preserves documentation and type information
42+
43+
The generated MCP server can be used with any MCP client, such as Claude.

0 commit comments

Comments
 (0)