mcp-server-any-openapi

# MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool [](https://hub.docker.com/r/buryhuang/mcp-server-any-openapi) [](https://opensource.org/licenses/MIT) ## TODO - The docker image is 2GB without pre-downloaded models. Its 3.76GB with pre-downloaded models!! Too big, someone please help me to reduce the size. ## Configuration Customize through environment variables. **GLOBAL_TOOL_PROMPT** is **IMPORTANT**! - `OPENAPI_JSON_DOCS_URL`: URL to the OpenAPI specification JSON (defaults to https://api.staging.readymojo.com/openapi.json) - `MCP_API_PREFIX`: Customizable tool namespace (default "any_openapi"): ```bash # Creates tools: custom_api_request_schema and custom_make_request docker run -e MCP_API_PREFIX=finance ... ``` - `GLOBAL_TOOL_PROMPT`: Optional text to prepend to all tool descriptions. This is crucial to make the Claude select and not select your tool accurately. ```bash # Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ... ``` ## TL'DR **Why I create this**: I want to serve my private API, whose swagger openapi docs is a few hundreds KB in size. - Claude MCP simply error on processing these size of file - I attempted convert the result to YAML, not small enough and a lot of errors. FAILED - I attempted to provide a API category, then ask MCP Client (Claude Desktop) to get the api doc by group. Still too big, FAILED. Eventually I came down to this solution: - It uses in-memory semantic search to find relevant Api endpoints by natural language (such as list products) - It returns the complete end-point docs (as I designed it to store one endpoint as one chunk) in millionseconds (as it's in memory) **Boom**, Claude now knows what API to call, with the **full parameters**! Wait I have to create another tool in this server to make the actual restful request, because "fetch" server simply don't work, and I don't want to debug why. https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0 Technical highlights: ```python query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop) MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response ``` ## Features - 🧠 Use remote openapi json file as source, no local file system access, no updating required for API changes - 🔍 Semantic search using optimized MiniLM-L3 model (43MB vs original 90MB) - 🚀 FastAPI-based server with async support - 🧠 Endpoint based chunking OpenAPI specs (handles 100KB+ documents), no loss of endpoint context - ⚡ In-memory FAISS vector search for instant endpoint discovery ## Limitations - Not supporting linux/arm/v7 (build fails on Transformer library) - 🐢 Cold start penalty (~15s for model loading) if not using docker image - [Obsolete] Current docker image disabled downloading models. You have a dependency over huggingface. When you load the Claude Desktop, it takes some time to download the model. If huggingface is down, your server will not start. - The latest docker image is embedding pre-downloaded models. If there is issues, I would revert to the old one. ## Multi-instance config example Here is the multi-instance config example. I design it so it can more flexibly used for multiple set of apis: ```json { "mcpServers": { "finance_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'", "buryhuang/mcp-server-any-openapi:latest" ] }, "healthcare_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json", "-e", "MCP_API_PREFIX=healthcare", "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for Healthcare API services efg.com .", "buryhuang/mcp-server-any-openapi:latest" ] } } } ``` In this example: - The server will automatically extract base URLs from the OpenAPI docs: - `https://api.finance.com` for finance APIs - `https://api.healthcare.com` for healthcare APIs - You can optionally override the base URL using `API_REQUEST_BASE_URL` environment variable: ```json { "mcpServers": { "finance_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json", "-e", "API_REQUEST_BASE_URL=https://api.finance.staging.com", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'", "buryhuang/mcp-server-any-openapi:latest" ] } } } ``` ## Claude Desktop Usage Example Claude Desktop Project Prompt: ``` You should get the api spec details from tools financial_api_request_schema You task is use financial_make_request tool to make the requests to get response. You should follow the api spec to add authorization header: Authorization: Bearer <xxxxxxxxx> Note: The base URL will be returned in the api_request_schema response, you don't need to specify it manually. ``` In chat, you can do: ``` Get prices for all stocks ``` ## Installation ### Installing via Smithery To install Scalable OpenAPI Endpoint Discovery and API Request Tool for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@baryhuang/mcp-server-any-openapi): ```bash npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude ``` ### Using pip ```bash pip install mcp-server-any-openapi ``` ## Available Tools The server provides the following tools (where `{prefix}` is determined by `MCP_API_PREFIX`): ### {prefix}_api_request_schema Get API endpoint schemas that match your intent. Returns endpoint details including path, method, parameters, and response formats. **Input Schema:** ```json { "query": { "type": "string", "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')" } } ``` ### {prefix}_make_request **Essential for reliable execution** with complex APIs where simplified implementations fail. Provides: **Input Schema:** ```json { "method": { "type": "string", "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "url": { "type": "string", "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)" }, "headers": { "type": "object", "description": "Request headers (optional)", "additionalProperties": { "type": "string" } }, "query_params": { "type": "object", "description": "Query parameters (optional)", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "description": "Request body for POST, PUT, PATCH (optional)" } } ``` **Response Format:** ```json { "status_code": 200, "headers": { "content-type": "application/json", ... }, "body": { // Response data } } ``` ## Docker Support ### Multi-Architecture Builds Official images support 3 platforms: ```bash # Build and push using buildx docker buildx create --use docker buildx build --platform linux/amd64,linux/arm64 \ -t buryhuang/mcp-server-any-openapi:latest \ --push . ``` ### Flexible Tool Naming Control tool names through `MCP_API_PREFIX`: ```bash # Produces tools with "finance_api" prefix: docker run -e MCP_API_PREFIX=finance_ ... ``` ### Supported Platforms - linux/amd64 - linux/arm64 ### Option 1: Use Prebuilt Image (Docker Hub) ```bash docker pull buryhuang/mcp-server-any-openapi:latest ``` ### Option 2: Local Development Build ```bash docker build -t mcp-server-any-openapi . ``` ### Running the Container ```bash docker run \ -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \ -e MCP_API_PREFIX=finance \ buryhuang/mcp-server-any-openapi:latest ``` ### Key Components 1. **EndpointSearcher**: Core class that handles: - OpenAPI specification parsing - Semantic search index creation - Endpoint documentation formatting - Natural language query processing 2. **Server Implementation**: - Async FastAPI server - MCP protocol support - Tool registration and invocation handling ### Running from Source ```bash python -m mcp_server_any_openapi ``` ## Integration with Claude Desktop Configure the MCP server in your Claude Desktop settings: ```json { "mcpServers": { "any_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .", "buryhuang/mcp-server-any-openapi:latest" ] } } } ``` ## Contributing 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the terms included in the LICENSE file. ## Implementation Notes - **Endpoint-Centric Processing**: Unlike document-level analysis that struggles with large specs, we index individual endpoints with: - Path + Method as unique identifiers - Parameter-aware embeddings - Response schema context - **Optimized Spec Handling**: Processes OpenAPI specs up to 10MB (~5,000 endpoints) through: - Lazy loading of schema components - Parallel parsing of path items - Selective embedding generation (omits redundant descriptions)