使用说明

OpenAPI MCP 服务器

一个用于创建的命令行界面（CLI）工具 STDIO（默认）、SSE 或 HTTP MCP 服务器 来自具有完全Cursor兼容性的OpenAPI规范。

特点

🔌（电源插头/插座） STDIO MCP 服务器（默认） - 通过标准输入/输出（stdin/stdout）与MCP通信，以进行本地/托管执行
🌐（表示互联网或世界） 远程MCP服务器 - 基于HTTP，使用服务器发送事件（SSE）或普通HTTP
🔧 修理工具或螺丝刀的象征 所有终端都成为工具 （非资源）以实现最大光标的兼容性
📡（天线或卫星信号的图标，无具体文字含义，可随语境理解为“信号”、“通讯”等概念） 支持URL和本地文件 作为OpenAPI规范的源代码
🔐（锁形符号，常用于表示密码或保密） 多种身份验证方法 (API密钥，承载令牌，基本认证)
🐳 这个表情符号通常代表“鲸鱼”或“海豚”，在中文中可以简单地翻译为“鲸鱼”或根据上下文意译为更贴切的表达，比如“海豚”或“鲸鲸”（一种可爱的昵称形式）。由于表情符号的含义有时具有一定的主观性和文化背景依赖性，具体翻译可能需根据语境调整。 Docker 镜像 便于分发和部署
⚡（闪电符号，常用于表示速度、活力或紧急情况） 基于FastMCP构建 支持原生SSE和HTTP传输
🌐（地球/互联网） 现代Python 3.12 以获得最佳性能

建筑学

此工具支持两种操作模式：

**STDIO（默认）**通过标准输入/输出（stdin/stdout）使用MCP JSON-RPC进行通信。非常适合本地工具以及直接从MCP客户端启动服务器的情况（例如，通过Docker） -i）。
远程HTTP为MCP提供服务/覆盖 服务器发送事件（SSE） 或者 明文HTTP非常适合远程/网络化的MCP客户端以及网页集成。

快速入门

使用 Docker（推荐）

# Build the image
docker build -t openapi-mcp-server .

# Run STDIO server (default)
# Note: use -i (no -t). stdout carries protocol; logs go to stderr.
docker run --rm -i --init openapi-mcp-server https://api.example.com/openapi.json

# Run SSE server
docker run -p 8000:8000 openapi-mcp-server https://api.example.com/openapi.json --server-type sse

# Run with authentication
docker run -p 8000:8000 -e API_KEY=your_key openapi-mcp-server \
  https://api.example.com/openapi.json --auth-type api_key

# Run with local file
docker run -p 8000:8000 -v $(pwd)/specs:/app/specs openapi-mcp-server \
  /app/specs/openapi.yaml --auth-type bearer --bearer-token YOUR_TOKEN

# Custom port and host
docker run -p 9000:9000 openapi-mcp-server \
  https://api.example.com/openapi.json --port 9000 --host 0.0.0.0

本地开发

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Run STDIO server (default)
openapi-mcp-server https://api.example.com/openapi.json
openapi-mcp-server ./openapi.yaml --auth-type api_key --api-key YOUR_KEY

# Run HTTP server
openapi-mcp-server https://api.example.com/openapi.json --server-type http

使用示例

来自URL

openapi-mcp-server https://api.example.com/openapi.json
# Default: STDIO mode over stdin/stdout
# For SSE instead: add `--server-type sse` and map a port

从本地文件

openapi-mcp-server ./openapi.yaml --auth-type api_key --api-key YOUR_KEY --port 8080
# Default: STDIO mode
# For SSE: `--server-type sse` and check http://localhost:8080/sse

### HTTP Transport
```bash
openapi-mcp-server https://api.example.com/openapi.json --server-type http
# Server runs at http://localhost:8000


### With Authentication
```bash
# API Key
openapi-mcp-server openapi.json --auth-type api_key --api-key YOUR_KEY

# Bearer Token
openapi-mcp-server openapi.json --auth-type bearer --bearer-token YOUR_TOKEN

# Basic Auth
openapi-mcp-server openapi.json --auth-type basic --username user --password pass

# With Custom Headers
openapi-mcp-server openapi.json --header "X-Custom-Header: value" --header "User-Agent: MyApp/1.0"

# With operation filtering
openapi-mcp-server openapi.json --methods GET,POST --include-paths "/api/.*"
openapi-mcp-server openapi.json --exclude-paths "/admin/.*" --exclude-tags "admin"

查询字符串中的API密钥（例如，Shodan期望?key=...）

# CLI example
openapi-mcp-server https://developer.shodan.io/api/openapi.json \
  --auth-type api_key \
  --api-key "$SHODAN_KEY" \
  --api-key-location query \
  --api-key-param-name key

使用环境变量

export API_KEY=your_api_key
export BEARER_TOKEN=your_bearer_token
export SERVER_TYPE=stdio   # or sse|http

# Header-based API key auth (default)
openapi-mcp-server openapi.json --auth-type api_key --host 0.0.0.0 --port 8000

# Query-parameter API key auth (e.g., Shodan expects ?key=...)
export API_KEY_LOCATION=query
export API_KEY_PARAM_NAME=key
openapi-mcp-server openapi.json --auth-type api_key

光标配置

添加到您的Cursor MCP配置中，用于 SSE 远程连接：

{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:8000/sse"
    }
  }
}

光标配置（通过Docker使用STDIO）

你也可以通过Docker使用STDIO来启动服务器（推荐用于本地使用）：

{
  "mcpServers": {
    "my-api-stdio": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--init",
        "openapi-mcp-server",
        "https://api.example.com/openapi.json",
        "--server-type", "stdio"
      ]
    }
  }
}

注：

不要传递 Docker -t 在STDIO模式下的TTY（电传打字机/终端）；它可能会破坏帧格式。
使用 -i 保持标准输入流打开。

服务器端点

当服务器运行时，它会暴露：

/sse - 主MCP服务器发送事件端点（SSE模式）
/ - 基础HTTP端点（HTTP模式）（在STDIO模式下没有HTTP端点；协议通过stdin/stdout传输。）

Docker 命令

构建

docker build -t openapi-mcp-server .

运行示例

# Basic usage
docker run -p 8000:8000 openapi-mcp-server https://api.example.com/openapi.json --server-type sse

# With environment file
docker run -p 8000:8000 --env-file .env openapi-mcp-server https://api.example.com/openapi.json --server-type sse

# With local spec file
docker run -p 8000:8000 -v $(pwd)/specs:/app/specs openapi-mcp-server /app/specs/api.json --server-type sse

# With custom headers
docker run -p 8000:8000 openapi-mcp-server https://api.example.com/openapi.json \
  --server-type sse \
  --header "X-Custom-Header: value" --header "User-Agent: MyApp/1.0"

# Background mode
docker run -d -p 8000:8000 --name my-mcp-server openapi-mcp-server https://api.example.com/openapi.json --server-type sse

# Check server status
curl http://localhost:8000/health
curl http://localhost:8000/

命令行选项

openapi-mcp-server [OPTIONS] OPENAPI_SOURCE

Options:
  --name TEXT                Server name
  --host TEXT                Host to bind (default: 0.0.0.0)
  --port INTEGER             Port to bind (default: 8000)
  --base-url TEXT            Override base URL for API requests
  --debug                    Enable debug logging
  --server-type [sse|http|stdio]   Transport type for FastMCP server (default: stdio)
  --auth-type [none|api_key|bearer|basic]  Authentication type
  --api-key TEXT             API key (or set API_KEY env var)
  --api-key-header TEXT      Header name for API key (default: X-API-Key)
  --bearer-token TEXT        Bearer token (or set BEARER_TOKEN env var)
  --username TEXT            Username for basic auth (or set USERNAME env var)
  --password TEXT            Password for basic auth (or set PASSWORD env var)
  --header TEXT              Custom header in format "Name: Value" (can be used multiple times)
  --methods TEXT             Comma-separated HTTP methods to include (e.g., "GET,POST,PUT")
  --include-paths TEXT       Comma-separated path patterns to include (supports regex)
  --exclude-paths TEXT       Comma-separated path patterns to exclude (supports regex)
  --include-tags TEXT        Comma-separated tags to include
  --exclude-tags TEXT        Comma-separated tags to exclude
  --help                     Show this message and exit

要求

Python 3.11+（推荐使用3.12以获得最佳性能）
FastMCP 2.0+
原生SSE传输（内置在FastMCP中）
httpx（用于HTTP请求）
点击（CLI界面）
PyYAML（YAML 支持）

SSE vs Stdio

这个实现使用了 通过HTTP的服务器发送事件 而不是使用标准I/O（stdio）：

✅ SSE福利

远程访问 - 可从任何地方连接
网页浏览器兼容 - 与基于网络的MCP客户端兼容
多个客户端 - 可以处理多个连接
标准HTTP - 可通过防火墙和代理工作
健康检查 - 内置监控端点

📋 代表“清单”或“待办事项列表”的意思。何时使用

远程MCP客户端
基于网络的应用程序
多客户端场景
生产部署
Docker/云环境

建筑细节

这个工具遵循 FastMCP OpenAPI 集成模式：

加载OpenAPI规范 来自文件或URL
创建经过身份验证的HTTP客户端 基于认证参数
将所有终端强制导向工具（或“工具页面”） 使用自定义路由映射（与Cursor兼容）
作为HTTP服务器运行 使用FastMCP的原生SSE或HTTP传输
通过服务器发送事件（Server-Sent Events）提供MCP服务 在 /sse 端点（SSE模式）或基础HTTP（HTTP模式）

为什么选择所有工具？

默认情况下，FastMCP 将 GET 端点映射到资源，将其他方法映射到工具。为了最大程度地兼容 Cursor，此工具强制执行 所有终点都将成为工具，以避免任何与资源相关的兼容性问题。

环境变量

API_KEY API密钥用于身份验证
BEARER_TOKEN - 用于认证的承载令牌
USERNAME - 基本认证的用户名
PASSWORD - 基本身份验证的密码

OpenAPI MCP服务器工具

使用说明

OpenAPI MCP 服务器

特点

建筑学

快速入门

使用 Docker（推荐）

本地开发

使用示例

来自URL

从本地文件

查询字符串中的API密钥（例如，Shodan期望?key=...）

使用环境变量

光标配置

光标配置（通过Docker使用STDIO）

服务器端点

Docker 命令

构建

运行示例

命令行选项

要求

SSE vs Stdio

✅ SSE福利

📋 代表“清单”或“待办事项列表”的意思。何时使用

建筑细节

为什么选择所有工具？

环境变量

另请参阅

使用说明

OpenAPI MCP 服务器

特点

建筑学

快速入门

使用 Docker（推荐）

本地开发

使用示例

来自URL

从本地文件

查询字符串中的API密钥（例如，Shodan期望?key=...）

使用环境变量

光标配置

光标配置（通过Docker使用STDIO）

服务器端点

Docker 命令

构建

运行示例

命令行选项

要求

SSE vs Stdio

✅ SSE福利

📋 代表“清单”或“待办事项列表”的意思。 何时使用

建筑细节

为什么选择所有工具？

环境变量

另请参阅

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器

📋 代表“清单”或“待办事项列表”的意思。何时使用