GitHub - baryhuang/mcp-server-any-openapi: A MCP server that enables Claude to discover and call any API endpoint through semantic search. Intelligently chunks OpenAPI specifications to handle large API documentation, with built-in request execution capabilities. Perfect for integrating private APIs with Claude Desktop. (original) (raw)

MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

Docker Hub License: MIT

TODO

Configuration

Customize through environment variables. GLOBAL_TOOL_PROMPT is IMPORTANT!

Creates tools: custom_api_request_schema and custom_make_request

docker run -e MCP_API_PREFIX=finance ...

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.

Eventually I came down to this solution:

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.

0208.any.openapi.demo1.mp4

Technical highlights:

query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop) MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

Features

Limitations

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:

{ "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:

{ "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:

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

Using pip

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:

{ "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:

{ "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:

{ "status_code": 200, "headers": { "content-type": "application/json", ... }, "body": { // Response data } }

Docker Support

Multi-Architecture Builds

Official images support 3 platforms:

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:

Produces tools with "finance_api" prefix:

docker run -e MCP_API_PREFIX=finance_ ...

Supported Platforms

Option 1: Use Prebuilt Image (Docker Hub)

docker pull buryhuang/mcp-server-any-openapi:latest

Option 2: Local Development Build

docker build -t mcp-server-any-openapi .

Running the Container

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

python -m mcp_server_any_openapi

Integration with Claude Desktop

Configure the MCP server in your Claude Desktop settings:

{ "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