mcp-api-connect

一个载荷输入，任意 API 输出。 mcp-api-connect 是一个协议和认证无关的连接器引擎：只需描述一次目标服务（URL、协议、认证、请求/响应形状），然后向其发送标准化载荷并获取标准化响应——无论目标是 REST/JSON API、遗留 SOAP 服务，还是受 API 密钥、Basic 认证、Bearer 令牌或 OAuth2 客户端凭据保护的服务。

它基于同一核心引擎提供三种使用方式，因此无论你想怎么用，都可以：

• Python 库 — pip install mcp-api-connect，直接调用 MCPAPIConnectEngine，无需服务器。

• 独立 HTTP API — pip install mcp-api-connect[api]，运行 mcp-api-connect-api，向 /invoke 发送 POST 请求。

• MCP 服务器 — pip install mcp-api-connect[mcp]，运行 mcp-api-connect，将任何 MCP 客户端（如 Claude）指向它，使代理能够将已注册的连接器——或任意服务——作为工具调用。

为什么

每个集成项目都在重复造轮子：这里一个 REST 客户端，那里一个 SOAP 客户端，每个服务一种认证流程，临时请求/响应映射散落在代码库各处。mcp-api-connect 将其集中到一个声明式规范（InvokeSpec）和一个执行引擎中，因此添加新目标服务只是配置，而非代码。

Related MCP server: Universal API Connector MCP

快速入门（库）

pip install mcp-api-connect

import asyncio
from mcp_api_connect import MCPAPIConnectEngine, InvokeSpec, Target, AuthSpec, AuthType, RequestFormat, ResponseFormat

spec = InvokeSpec(
    target=Target(base_url="https://api.example.com"),
    auth=AuthSpec(type=AuthType.API_KEY, config={"api_key": "secret", "header_name": "X-API-Key"}),
    request_format=RequestFormat(method="POST", path="/v1/orders", content_type="json"),
    response_format=ResponseFormat(content_type="json"),
)

async def main():
    async with MCPAPIConnectEngine() as engine:
        result = await engine.invoke(spec, {"customer": "jane"})
        print(result.success, result.data)

asyncio.run(main())

快速入门（HTTP API）

pip install "mcp-api-connect[api]"
mcp-api-connect-api   # serves on :8000, interactive docs at /docs

curl -X POST http://localhost:8000/invoke -H 'content-type: application/json' -d '{
  "spec": {
    "target": {"base_url": "https://api.example.com"},
    "auth": {"type": "api_key", "config": {"api_key": "secret"}},
    "request_format": {"method": "POST", "path": "/v1/orders"},
    "response_format": {"content_type": "json"}
  },
  "payload": {"customer": "jane"}
}'

注册一次可复用的连接器，然后按名称调用它：

curl -X POST http://localhost:8000/connectors -d '{"name": "orders-api", "spec": {...}}'
curl -X POST http://localhost:8000/connectors/orders-api/invoke -d '{"customer": "jane"}'

快速入门（MCP）

pip install "mcp-api-connect[mcp]"

{
  "mcpServers": {
    "mcp-api-connect": { "command": "/path/to/.venv/bin/mcp-api-connect" }
  }
}

暴露工具：invoke（无状态、一次性）、register_connector、list_connectors、invoke_connector（按名称）、delete_connector。代理可以一次性为“Salesforce API”注册连接器，然后只需说“用这个载荷调用它”即可。

➜ 完整的 Claude Desktop / Claude Code / Cursor 设置、持久化、安全说明和实际示例：docs/mcp-integration.md。

核心概念

• Target — 基础 URL、协议（rest | soap）、超时、默认请求头。

• AuthSpec — type（none、api_key、basic、bearer、oauth2_client_credentials）加上针对该类型定制的 config 字典。OAuth2 令牌会自动获取并缓存。

• RequestFormat / ResponseFormat — 内容类型（json、xml、soap）加上声明式 field_map（{"target.path": "$.source.jsonpath"}）用于无需编写代码即可重塑载荷，或使用 Jinja2 body_template 进行完全控制（SOAP 信封必需）。

• InvokeSpec — 将上述三者捆绑在一起；是“如何访问一个服务”的单元。将其存储为命名 Connector 或每次调用时内联传递。

完整模式参见 src/mcp_api_connect/core/models.py，每种认证 type 所需的 config 形状参见 docs/auth-reference.md。

文档

• docs/mcp-integration.md — 完整的 MCP 客户端设置（Claude Desktop、Claude Code、Cursor）、持久化、安全、工具参考、实际示例、故障排除

• docs/auth-reference.md — 每种认证类型的 config 字段

• CONTRIBUTING.md — 开发环境设置、运行测试、PR 期望

扩展

• 新认证类型：实现 AuthStrategy，通过 engine.register_auth_strategy(...) 注册。

• 新协议（例如 GraphQL）：实现 ProtocolAdapter，通过 engine.register_adapter(...) 注册。

• 新连接器存储后端：实现 ConnectorStore（附带 InMemoryConnectorStore 和 SqliteConnectorStore，凭据通过 Fernet 静态加密）。

路线图

• OAuth2 授权码流程、mTLS、AWS SigV4 认证策略

• WSDL 驱动的 SOAP（可选 zeep 后端适配器，无需手写信封）

• GraphQL 适配器

• 基于 Postgres 的 ConnectorStore

• 每个连接器的重试/退避和速率限制策略

• 面向公共部署的 SSRF 安全目标白名单

开发

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,storage,mcp]"
pytest

许可证

MIT — 参见 LICENSE。