OpenAPI MCP Bridge
A generic MCP server that takes any OpenAPI/Swagger specification and exposes it as MCP tools, allowing AI assistants to search, explore, and execute any REST API.
Architecture
+------------------+
| Claude / AI |
+--------+---------+
|
| MCP Protocol
v
+------------------------------------------------------------------+
| OpenAPI MCP Bridge |
| |
| +-------------+ +-------------+ +------------------+ |
| | Config | | Parser | | Registry | |
| | (apis.json) |--->| (OpenAPI) |--->| (API endpoints) | |
| +-------------+ +-------------+ +------------------+ |
| | |
| +-------------+ +-------------+ +--------v---------+ |
| | Guardrails | | Search | | Executor | |
| | (safety) | | (fuzzy) | | (httpx) | |
| +-------------+ +-------------+ +------------------+ |
| | |
+------------------------------------------------------------------+
|
v
+------------------+
| REST APIs |
| (Petstore, etc) |
+------------------+Quick Start
Installation
# Clone the repository
git clone https://github.com/your-username/openapi-mcp-bridge.git
cd openapi-mcp-bridge
# Install with uv
uv sync --all-extras
# Or with pip
pip install -e ".[dev]"Register an API
Edit config/apis.json to add your API:
{
"apis": [
{
"name": "my-api",
"spec_url": "https://api.example.com/openapi.json",
"base_url": "https://api.example.com",
"auth": {
"type": "bearer",
"token": "$MY_API_TOKEN",
"header_name": "Authorization"
},
"settings": {
"default_page_size": 20,
"confirm_destructive": true
}
}
]
}Xquik API Example
For a real authenticated OpenAPI 3.1 API, copy config/xquik.apis.example.json to your active config and set XQUIK_API_KEY. The example registers Xquik's public spec for X/Twitter automation, trends, tweet search, media, monitor, and webhook endpoints.
Run the Server
# Run with fuzzy search (default)
python -m src.server
# Run with embedding search (better semantic understanding)
python -m src.server --search-provider embedding
# Or set via environment variable
SEARCH_PROVIDER=embedding python -m src.serverInstall Embedding Search (Optional)
For better semantic search using sentence-transformers:
# With uv
uv pip install "sentence-transformers>=2.2.0" "numpy>=1.24.0"
# Or with pip
pip install sentence-transformers numpyConfiguration Reference
API Configuration
| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique identifier for the API | | spec_url | string | Yes | URL or local path to OpenAPI spec | | base_url | string | Yes | Base URL for API requests | | auth | object | No | Authentication configuration | | settings | object | No | API-specific settings |
Authentication Types
| Type | Description | Example | |------|-------------|---------| | bearer | Bearer token in Authorization header | Authorization: Bearer <token> | | api_key | API key in header or query param | X-API-Key: <token> | | basic | Basic auth (base64 encoded) | Authorization: Basic <base64> | | none | No authentication | - |
Environment variables can be referenced with $VAR_NAME syntax.
Settings
| Setting | Default | Description | |---------|---------|-------------| | default_page_size | 20 | Default limit for list responses | | max_batch_size | 50 | Maximum requests in batch execution | | rate_limit_per_second | 5 | Rate limiting for requests | | confirm_destructive | true | Require confirmation for DELETE/PUT/PATCH |
Search Providers
Fuzzy Search (Default)
Uses thefuzz library for string matching. Fast and works without additional dependencies.
python -m src.server --search-provider fuzzyBest for: Exact keyword matching, operation IDs, path names.
Embedding Search
Uses sentence-transformers for semantic similarity. Better understanding of synonyms and intent.
python -m src.server --search-provider embeddingBest for: Natural language queries, synonym matching, semantic similarity.
Comparison:
| Query | Fuzzy | Embedding | |-------|-------|-----------| | "find all pets" | High confidence | High confidence | | "what animals are available" | Low confidence | High confidence | | "buy a pet" | Mixed results | Finds store/order | | "remove a specific animal" | Mixed results | Finds DELETE pet |
Tool Reference
1. list_apis
List all registered OpenAPI/Swagger APIs.
Input: None
Output: ``json [ { "name": "petstore", "base_url": "https://petstore.example.com", "description": "Pet Store API", "auth_type": "api_key", "endpoint_count": 15 } ] ``
2. search_endpoints
Search for API endpoints by natural language description.
Input: ``json { "api": "petstore", "query": "find all available pets", "limit": 5 } ``
Output: ``json { "api": "petstore", "query": "find all available pets", "results": [ { "endpoint": { "path": "/pet/findByStatus", "method": "GET", "summary": "Finds Pets by status", "parameters": [...] }, "similarity_score": 0.85, "low_confidence": false } ], "total_results": 5 } ``
3. execute_endpoint
Execute an API endpoint.
Input: ``json { "api": "petstore", "path": "/pet/{petId}", "method": "GET", "params": {"petId": 123}, "limit": 20, "offset": 0, "confirmed": false } ``
Output: ``json { "status_code": 200, "data": {"id": 123, "name": "Buddy", "status": "available"}, "truncated": false, "auth_error": false } ``
For destructive operations (DELETE, PUT, PATCH), set confirmed: true.
4. batch_execute
Execute multiple API endpoints in parallel.
Input: ``json { "api": "petstore", "requests": [ {"path": "/pet/1", "method": "GET"}, {"path": "/pet/2", "method": "GET"}, {"path": "/pet/3", "method": "GET"} ], "parallel": true, "confirmed": true } ``
Output: ``json { "results": [...], "summary": {"total": 3, "succeeded": 3, "failed": 0} } ``
Usage Examples
Example 1: Simple Query
User: What pets are available in the store?
AI: Let me search for that endpoint and get the data.
1. search_endpoints(api="petstore", query="find available pets")
2. execute_endpoint(api="petstore", path="/pet/findByStatus",
method="GET", params={"status": "available"})
Result: Found 6 available pets: Buddy (dog), Whiskers (cat), ...Example 2: Creating a Resource
User: Add a new pet named "Max" to the store.
AI: 1. search_endpoints(api="petstore", query="create new pet")
2. execute_endpoint(api="petstore", path="/pet", method="POST",
body={"name": "Max", "species": "dog", "status": "available"})
Result: Created pet with ID 15.Example 3: Destructive Operation
User: Delete pet #15.
AI: 1. execute_endpoint(api="petstore", path="/pet/{petId}", method="DELETE",
params={"petId": 15}, confirmed=false)
Warning: This is a destructive operation. Set confirmed=true to proceed.
User: Yes, go ahead.
AI: 2. execute_endpoint(..., confirmed=true)
Result: Pet #15 deleted successfully.Claude Desktop Integration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"openapi-bridge": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/openapi-mcp-bridge",
"env": {
"PETSTORE_KEY": "your-api-key"
}
}
}
}Claude Code Integration
Create .mcp.json in your project root:
{
"mcpServers": {
"openapi-bridge": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/openapi-mcp-bridge",
"env": {
"PETSTORE_KEY": "your-api-key"
}
}
}
}Testing
Run Unit Tests
pytest tests/test_parser.py tests/test_search.py tests/test_executor.py -vRun Integration Tests
# Requires mock server to start automatically
pytest tests/test_integration.py -vStart Mock Server Manually
cd mock-petstore
./run.shDevelopment
Project Structure
openapi-mcp-bridge/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP server with 4 tools
│ ├── config.py # Configuration loader
│ ├── parser.py # OpenAPI spec parser
│ ├── registry.py # API registry
│ ├── executor.py # HTTP request executor
│ ├── guardrails.py # Safety checks
│ └── search/
│ ├── base.py # Search interface
│ ├── fuzzy.py # Fuzzy search
│ └── embedding.py # Embedding search (placeholder)
├── config/
│ └── apis.json # API registrations
├── mock-petstore/ # Test server
├── tests/
└── pyproject.tomlLicense
MIT
