# FastMCP OpenAPI
A FastMCP wrapper that dynamically generates MCP (Model Context Protocol) tools from OpenAPI specifications.
## Quick Start
### Prerequisites
- Python 3.8+ with pip
- Node.js 16+ (for MCP Inspector)
- OpenAI API key (for LangChain demos)
### Installation
```bash
pip install fastmcp-openapi
```
### Basic Usage
```bash
# Generate MCP tools from any OpenAPI spec
fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json
# With authentication
fastmcp-openapi --spec https://api.example.com/openapi.json --auth-header "Bearer your-token"
# Multiple APIs
fastmcp-openapi --spec api1.json --spec api2.json --spec api3.json
```
### Test with MCP Inspector
```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector
# Test your OpenAPI tools
npx @modelcontextprotocol/inspector fastmcp-openapi --spec examples/simple_api.json
# Test Petstore API with Inspector
npx @modelcontextprotocol/inspector fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2
```
### Claude Desktop Integration
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"openapi-server": {
"command": "fastmcp-openapi",
"args": ["--spec", "https://api.example.com/openapi.json", "--auth-header", "Bearer your-token"]
}
}
}
```
## Features
- ✅ **Dynamic Tool Generation**: Converts OpenAPI operations to MCP tools automatically
- ✅ **Type Safety**: Full parameter validation using OpenAPI schemas
- ✅ **Authentication**: Bearer tokens, API keys, Basic auth
- ✅ **Multiple APIs**: Load multiple OpenAPI specs in one server
- ✅ **Real-time**: Add/remove APIs without restart
## Command Line Options
```bash
fastmcp-openapi --help
Options:
--spec TEXT OpenAPI specification URL or file path (can be used multiple times)
--name TEXT Server name (default: "OpenAPI Server")
--auth-header TEXT Authorization header (e.g., 'Bearer token123'). Must match order of --spec options.
--base-url TEXT Override base URL for API calls. Must match order of --spec options.
--config TEXT JSON config file with API specifications
--transport TEXT Transport: stdio, streamable-http, sse (default: stdio)
--port INTEGER Port for HTTP/SSE transport (default: 8000)
--debug Enable debug logging
```
## Programmatic Usage
```python
from fastmcp_openapi import OpenAPIServer
# Create server
server = OpenAPIServer("My API Server")
# Add OpenAPI specs
await server.add_openapi_spec(
name="petstore",
spec_url="https://petstore.swagger.io/v2/swagger.json",
auth_header="Bearer your-token"
)
# Run server
server.run()
```
## Examples
### Multiple APIs with Different Auth
```bash
# Multiple APIs with different base URLs and auth
fastmcp-openapi \
--spec https://petstore.swagger.io/v2/swagger.json \
--spec https://api.github.com/openapi.yaml \
--spec ./local-api.json \
--base-url https://petstore.swagger.io/v2 \
--base-url https://api.github.com \
--base-url http://localhost:3000 \
--auth-header "Bearer petstore-token" \
--auth-header "Bearer github-token" \
--auth-header "Basic local-auth"
# Each API gets its own tools with prefixes:
# - api_1_getPetById (Petstore)
# - api_2_getUser (GitHub)
# - api_3_createItem (Local API)
```
### Mixed API Sources
```bash
# Combine remote and local APIs
fastmcp-openapi \
--spec https://petstore.swagger.io/v2/swagger.json \
--spec examples/simple_api.json \
--spec https://jsonplaceholder.typicode.com/openapi.json \
--base-url https://petstore.swagger.io/v2 \
--base-url http://localhost:8080 \
--base-url https://jsonplaceholder.typicode.com
# Creates unified MCP server with tools from all APIs
```
### Authenticated API
```bash
fastmcp-openapi \
--spec https://api.example.com/openapi.json \
--auth-header "Bearer your-oauth-token" \
--base-url "https://api.example.com/v1"
```
### Development Mode
```bash
# HTTP mode for web testing
fastmcp-openapi \
--spec examples/simple_api.json \
--transport streamable-http \
--port 8080 \
--debug
# SSE mode for MCP Inspector
fastmcp-openapi \
--spec https://petstore.swagger.io/v2/swagger.json \
--base-url https://petstore.swagger.io/v2 \
--transport sse \
--port 8081 \
--debug
```
### LangChain Integration
```bash
# Install required dependencies
pip install langchain-openai langchain-mcp-adapters langgraph
# Set OpenAI API key
export OPENAI_API_KEY="your-openai-api-key"
# Start FastMCP server with HTTP transport
fastmcp-openapi \
--spec https://petstore.swagger.io/v2/swagger.json \
--base-url https://petstore.swagger.io/v2 \
--transport streamable-http \
--port 8081
# Run LangChain test (in another terminal)
python test_mcp_langchain.py
```
The LangChain integration allows AI agents to use the generated MCP tools for natural language interaction with APIs.
## How It Works
1. **Load OpenAPI Spec**: Fetches and parses OpenAPI/Swagger specifications
2. **Generate Tools**: Creates MCP tools for each API operation with proper schemas
3. **Handle Requests**: Validates parameters and makes authenticated HTTP requests
4. **Return Results**: Formats API responses for AI consumption
## Supported Features
- ✅ OpenAPI 3.0.x, 3.1.x, Swagger 2.0
- ✅ Path/query parameters, headers, request bodies
- ✅ Authentication (Bearer, API Key, Basic)
- ✅ Parameter validation and type checking
- ✅ Multiple APIs in one server
- ✅ Multiple transports: stdio, streamable-http, sse
- ✅ LangChain integration for AI agents
- ✅ MCP Inspector support for interactive testing
## Testing & Examples
### Quick Test with Petstore API
```bash
# 1. Start server with SSE transport
fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2 --transport sse --port 8081
# 2. Test with MCP Inspector (in another terminal)
npx @modelcontextprotocol/inspector fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2
# 3. Test with LangChain (requires OPENAI_API_KEY)
python test_mcp_langchain.py
```
### Available Transport Modes
- **`stdio`**: Standard input/output (default, for Claude Desktop)
- **`streamable-http`**: HTTP-based transport (for LangChain integration)
- **`sse`**: Server-Sent Events transport (for MCP Inspector)
## Multiple API Management
FastMCP OpenAPI supports combining multiple OpenAPI specifications into a single MCP server, each with their own base URLs and authentication.
### Configuration Methods
#### Method 1: JSON Configuration (Recommended)
Create a JSON config file to clearly define each API:
```json
{
"apis": [
{
"name": "petstore",
"spec": "https://petstore.swagger.io/v2/swagger.json",
"base_url": "https://petstore.swagger.io/v2",
"auth": "Bearer petstore-api-key"
},
{
"name": "simple_api",
"spec": "examples/simple_api.json",
"base_url": "http://localhost:8080"
}
]
}
```
```bash
# Use the config file
fastmcp-openapi --config examples/multi_api_config.json --transport sse --port 8081
```
#### Method 2: Command Line Arguments (Positional Matching)
⚠️ **Important**: Arguments must be in the same order - each `--base-url` and `--auth-header` matches the corresponding `--spec` by position.
```bash
# Order matters: spec[0]→base_url[0]→auth[0], spec[1]→base_url[1]→auth[1], etc.
fastmcp-openapi \
--spec https://petstore.swagger.io/v2/swagger.json \ # Position 0
--spec examples/simple_api.json \ # Position 1
--spec https://api.github.com/openapi.yaml \ # Position 2
--base-url https://petstore.swagger.io/v2 \ # Position 0 → spec[0]
--base-url http://localhost:8080 \ # Position 1 → spec[1]
--base-url https://api.github.com \ # Position 2 → spec[2]
--auth-header "Bearer petstore-key" \ # Position 0 → spec[0]
--auth-header "" \ # Position 1 → spec[1] (no auth)
--auth-header "Bearer github-key" # Position 2 → spec[2]
```
### Benefits
- **Unified Interface**: Access multiple APIs through one MCP server
- **Individual Configuration**: Each API can have its own base URL and auth
- **Tool Namespacing**: Tools are automatically prefixed to avoid conflicts
- **Mixed Sources**: Combine remote APIs, local services, and files
### Tool Naming Convention
When multiple APIs are loaded, tools are automatically prefixed:
- **Single API**: `operationId` → `getPetById`
- **Multiple APIs**: `api_name_operationId` → `petstore_getPetById`, `github_getUser`
## Development
```bash
git clone <repository>
cd fastmcp-openapi
pip install -e ".[dev]"
pytest
```
## License
MIT License
