Content
# MCP RESTful Adapter
Automatically converts RESTful APIs (Swagger 2.0 / OpenAPI 3.0) to MCP Server. Each API endpoint becomes an MCP Tool.
## Quick Start
### 1. Using in Claude Desktop / Cursor / Claude Code
Edit the configuration file (Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`):
**Install from PyPI (recommended):**
```json
{
"mcpServers": {
"petstore": {
"command": "uvx",
"args": ["mcp-restful-adapter"],
"env": {
"API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
"API_BASE_URL": "https://petstore3.swagger.io/api/v3",
"API_TAGS": "pet,store"
}
}
}
}
```
**Local development (before release):**
```json
{
"mcpServers": {
"petstore": {
"command": "uv",
"args": [
"run",
"--project", "/path/to/mcp-restful-adapter",
"mcp-restful-adapter"
],
"env": {
"API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
"API_BASE_URL": "https://petstore3.swagger.io/api/v3",
"API_TAGS": "pet,store"
}
}
}
}
```
> Replace `/path/to/mcp-restful-adapter` with the actual path to this project.
After configuration, Claude can directly call the Petstore API:
- `findPetsByStatus(status="available")` → Query available pets
- `getPetById(petId=1)` → Query pet details
- `addPet(name="Buddy", ...)` → Create a pet
### 2. Using in Terminal
```bash
# PyPI version
API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
API_BASE_URL=https://petstore3.swagger.io/api/v3 \
API_TAGS=pet \
uvx mcp-restful-adapter
# Local development
API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
API_BASE_URL=https://petstore3.swagger.io/api/v3 \
API_TAGS=pet \
uv run mcp-restful-adapter
```
### 3. APIs with Authentication
```json
{
"mcpServers": {
"my-api": {
"command": "uvx",
"args": ["mcp-restful-adapter"],
"env": {
"API_SPEC_URL": "https://your-api.example.com/openapi.json",
"API_BASE_URL": "https://your-api.example.com",
"API_HEADERS": "{\"Authorization\": \"Bearer your-bearer-token\", \"X-Tenant\": \"acme\"}"
}
}
}
}
```
## Environment Variables
| Variable | Description | Default |
| --- | --- | --- |
| `API_SPEC_URL` | OpenAPI/Swagger document URL | **Required** |
| `API_BASE_URL` | Backend API URL | **Required** |
| `API_TAGS` | Tag whitelist, comma-separated, **OR** logic (match any tag to keep) | All |
| `API_METHODS` | HTTP method whitelist, comma-separated | All |
| `API_PATHS` | Path regex whitelist (`re.search` match) | All |
| `API_PATHS_EXCLUDE` | Path regex blacklist (whitelist priority, see below) | None |
| `API_HEADERS` | Custom request headers (JSON format, including authentication) | Empty |
| `LOG_LEVEL` | Log level (`INFO` shows startup info, `DEBUG` records request headers and body) | `WARNING` |
### Whitelist / Blacklist Strategy
`API_PATHS` (whitelist) and `API_PATHS_EXCLUDE` (blacklist) work together, **whitelist priority**:
```
Whitelist hit → Pass (no blacklist check)
Whitelist miss + Blacklist hit → Exclude
Whitelist miss + Blacklist miss → Exclude
Only blacklist (no whitelist) → Pass if not in blacklist
```
Recommended configuration — Expose only read-only query interfaces:
```json
{
"API_METHODS": "GET",
"API_PATHS": "(?i)(get|query|detail|page|select|list|search|info|find|fetch|tree|export|download|template|count|stat|check|\\{[a-zA-Z]+\\})",
"API_PATHS_EXCLUDE": "(?i)(save|update|delete|remove|create|add|clear|sync|generate|import|handle|flush|send|complete|fix|reset|process|submit|approve|cancel|enable|disable|trigger|notify|push|pull|upload|revoke|grant|bind|unbind|transfer|lock|unlock|batch)"
}
```
### Filtering Examples
```bash
# Only GET requests
API_METHODS=GET
# Only pet or store related endpoints
API_TAGS=pet,store
# Only /api/v1/ prefixed paths
API_PATHS=^/api/v1/
# Exclude paths containing delete/remove (blacklist)
API_PATHS_EXCLUDE=(?i)(delete|remove)
# Combine: GET and POST under pet tag
API_TAGS=pet
API_METHODS=GET,POST
# Read-only query (whitelist + blacklist + GET)
API_METHODS=GET
API_PATHS=(?i)(get|query|detail|page|list|search)
API_PATHS_EXCLUDE=(?i)(save|update|delete|remove|create)
```
## Development
```bash
uv sync # Install dependencies
uv run mcp-restful-adapter # Run
uv run pytest tests/ -v # Run tests
uv run pytest tests/ --cov=mcp_restful_adapter # Coverage
```
## Example Code
| File | Description |
| --- | --- |
| [`examples/agent_usage.py`](examples/agent_usage.py) | Usage in Agent — Connect MCP Server, list tools, call tools |
| [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) | Claude Desktop configuration template |
```bash
uv run python examples/agent_usage.py
```
