O

OpenAPI服务

@baryhuang/mcp-server-any-openapi
2 Stars 516 次浏览 baryhuang 更新于 2026-08-23

该服务器通过语义搜索和高性能处理，促进对OpenAPI端点的可扩展发现和执行，克服了大规模规范处理的限制，实现了简化的API交互。

开发者工具搜索工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "any_openapi": {
      "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"
      ],
      "command": "docker"
    },
    "finance_openapi": {
      "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"
      ],
      "command": "docker"
    },
    "healthcare_openapi": {
      "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"
      ],
      "command": "docker"
    }
  }
}

该服务需要配置环境变量：MCP_API_PREFIX、OPENAPI_JSON_DOCS_URL

服务介绍

MCP Server: 可扩展的 OpenAPI 端点发现和 API 请求工具

Docker Hub

TODO

  • 该 Docker 镜像在没有预下载模型的情况下为 2GB。如果包含预下载的模型，大小则达到 3.76GB!! 太大了，希望有人能帮我减小它的体积。

TL'DR

我创建这个的原因：我想提供我的私有 API 服务，其 swagger openapi 文档大小为几百 KB。

  • Claude MCP 在处理这种大小的文件时会直接报错
  • 我尝试将结果转换为 YAML 格式，但仍然不够小并且有很多错误。失败了
  • 我尝试提供一个 API 类别，然后让 MCP 客户端（Claude Desktop）按组获取 API 文档。还是太大了，失败了。

最终我找到了这个解决方案：

  • 它使用内存中的语义搜索来通过自然语言（例如列出产品）查找相关的 API 端点
  • 它以毫秒级的速度返回完整的端点文档（因为我设计它将每个端点作为一个块存储）

就这样，Claude 现在知道要调用哪个 API 了，并且还带有全部参数！

等等，我还必须在这个服务器上创建另一个工具来进行实际的 RESTful 请求，因为“fetch”服务器根本不起作用，而且我不想去调试为什么。

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

技术亮点：

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

功能

  • 🧠 使用远程 openapi json 文件作为源，无需本地文件系统访问，API 更改时无需更新
  • 🔍 使用优化后的 MiniLM-L3 模型进行语义搜索（43MB 对比原始 90MB）
  • 🚀 基于 FastAPI 的服务器，支持异步
  • 🧠 基于端点分块的 OpenAPI 规范（处理 100KB+ 文档），不丢失端点上下文
  • ⚡ 内存中 FAISS 向量搜索实现即时端点发现

限制

  • 不支持 linux/arm/v7（在 Transformer 库上构建失败）
  • 🐢 如果不使用 Docker 镜像，冷启动会有惩罚（约 15 秒用于加载模型）
  • [过时] 当前 Docker 镜像禁用了下载模型的功能。你依赖于 Hugging Face。当你加载 Claude Desktop 时，需要一些时间来下载模型。如果 Hugging Face 出现故障，你的服务器将无法启动。
  • 最新的 Docker 镜像嵌入了预先下载好的模型。如果有问题，我会回退到旧版本。

多实例配置示例

这里是一个多实例配置的例子。我这样设计是为了更灵活地应用于多组 API：

{
  "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",
        "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",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

在此示例中：

  • 服务器将自动从 OpenAPI 文档中提取基础 URL：
    • https://api.finance.com 用于金融 API
    • https://api.healthcare.com 用于医疗保健 API
  • 你可以选择使用 API_REQUEST_BASE_URL 环境变量覆盖基础 URL：
{
  "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",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude Desktop 使用示例

Claude Desktop 项目提示：

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.

在聊天中，你可以这样做：

Get prices for all stocks

安装

请注意，原文档中的代码块 #0, #1, #2, #3, 和 #4 被保留为占位符，具体的代码内容应根据实际情况填写。

通过 Smithery 安装

通过 Smithery 自动安装 Scalable OpenAPI Endpoint Discovery 和 API Request Tool for Claude Desktop：

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

使用 pip

pip install mcp-server-any-openapi

配置

通过环境变量自定义：

  • OPENAPI_JSON_DOCS_URL: OpenAPI 规范 JSON 的 URL（默认为 https://api.staging.readymojo.com/openapi.json）
  • MCP_API_PREFIX: 可自定义的工具命名空间（默认为 "any_openapi"）： 
    # 创建工具: custom_api_request_schema 和 custom_make_request
docker run -e MCP_API_PREFIX=finance ...

可用工具

服务器提供以下工具（其中 {prefix} 由 MCP_API_PREFIX 决定）：

{prefix}_api_request_schema

获取与您的意图匹配的 API 端点模式。返回端点详细信息，包括路径、方法、参数和响应格式。

输入模式：

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

对于简化实现失败的复杂 API 可靠执行必不可少。提供：

输入模式：

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

响应格式：

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

Docker 支持

多架构构建

官方镜像支持 3 个平台：

# 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 .

灵活的工具命名

通过 MCP_API_PREFIX 控制工具名称：

# Produces tools with "finance_api" prefix:
docker run -e MCP_API_PREFIX=finance_ ...

支持的平台

  • linux/amd64
  • linux/arm64

选项 1：使用预构建镜像（Docker Hub）

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

选项 2：本地开发构建

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

运行容器

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

关键组件

  1. EndpointSearcher: 核心类，处理：

    • OpenAPI 规范解析
    • 语义搜索索引创建
    • 端点文档格式化
    • 自然语言查询处理

  2. 服务器实现：

    • 异步 FastAPI 服务器
    • MCP 协议支持
    • 工具注册和调用处理

从源代码运行

python -m mcp_server_any_openapi

与 Claude Desktop 集成

在您的 Claude Desktop 设置中配置 MCP 服务器：

{
  "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",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

贡献

  1. 分叉仓库
  2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开一个 Pull Request

许可证

本项目根据 LICENSE 文件中包含的条款进行许可。

实现说明

  • 以端点为中心的处理：与难以处理大型规范的文档级分析不同，我们通过以下方式索引单个端点：
    • 路径 + 方法作为唯一标识符
    • 参数感知嵌入
    • 响应模式上下文
  • 优化的规范处理：通过以下方式处理高达 10MB（约 5,000 个端点）的 OpenAPI 规范：
    • 模式组件的延迟加载
    • 路径项的并行解析
    • 选择性嵌入生成（省略冗余描述）
查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。