Mixpeek

Mixpeek MCP 服务

一个轻量、适合生产环境的 Mixpeek 模型上下文协议（MCP）服务，可：

• 自动加载 Mixpeek 的 OpenAPI 规范，并将端点公开为 MCP 工具
• 支持本地和托管使用（自备 API 密钥）
• 注入 Authorization 和 X-Namespace 标头
• 包含速率限制、超时和脱敏日志
• 提供 Docker 和简单配置

快速开始

1. 安装

Python（PyPI）：

# global (recommended)
pipx install mixpeek-mcp

# or in a venv
python -m venv .venv && source .venv/bin/activate
pip install mixpeek-mcp

npm（Node）：

# run once
npx @mixpeek/mcp

# or install globally
npm i -g @mixpeek/mcp

Homebrew（macOS）：

# tap and install (once the tap is live)
brew tap mixpeek/tap https://github.com/mixpeek/homebrew-tap
brew install mixpeek-mcp

# temporary local formula (dev/testing):
brew install --build-from-source Formula/mixpeek-mcp.rb

2. 配置（使用环境变量或 MCP 客户端密钥存储）

cp env.sample .env
# edit as needed

环境变量：

• MIXPEEK_API_KEY：Mixpeek API 密钥（如果端点无需身份验证，则可选）
• MIXPEEK_API_BASE：默认为 https://api.mixpeek.com
• MIXPEEK_OPENAPI_URL：默认为 <API_BASE>/openapi.json（或 /docs/openapi.json）
• MIXPEEK_NAMESPACE：可选的命名空间值，将通过 X-Namespace 发送
• MCP_RATE_MAX_CALLS：在 MCP_RATE_PER_SECONDS 时间内，默认为 20 次
• MCP_RATE_PER_SECONDS：默认为 10
• MCP_CONNECT_TIMEOUT：默认为 5
• MCP_READ_TIMEOUT：默认为 30

3. 在本地运行（stdio）

# PyPI
mixpeek-mcp

# from source
python server.py

# npm
mixpeek-mcp

你的 MCP 客户端（例如 Claude Desktop）可以通过 stdio 连接到此服务。

Docker

docker build -t mixpeek-mcp:latest .
docker run --rm -it \
  -e MIXPEEK_API_KEY=sk_... \
  -e MIXPEEK_NAMESPACE=your_namespace \
  mixpeek-mcp:latest

也可以拉取并运行（发布后）：

docker run --rm -it \
  -e MIXPEEK_API_KEY=sk_... \
  -e MIXPEEK_NAMESPACE=your_namespace \
  ghcr.io/mixpeek/mcp:latest

分发

• npm：@mixpeek/mcp → https://www.npmjs.com/package/@mixpeek/mcp
• PyPI：mixpeek-mcp → https://pypi.org/project/mixpeek-mcp/（待发布）
• Docker Hub：mixpeek/mcp（待推送），GHCR：ghcr.io/mixpeek/mcp（待推送）
• Homebrew：mixpeek/tap/mixpeek-mcp（待创建 tap 仓库）

提交到 Docker MCP Registry

我们已准备好与 Official Docker MCP Registry 兼容的 registry.json。提交步骤：

1. Fork 该注册表，并按照其 CONTRIBUTING 指南在相应目录下创建新条目。
2. 添加我们的 registry.json（如果你发布到不同的组织或标签，请更新 Docker 镜像引用）。
3. 发起 PR。获批后，它将出现在 MCP 目录和 Docker Desktop 的 MCP Toolkit 中。

配置

写入受保护的端点需要：

• MIXPEEK_API_KEY：Authorization: Bearer <key>

可选项：

• MIXPEEK_NAMESPACE：设置 X-Namespace 以实现隔离
• MIXPEEK_API_BASE：默认为 https://api.mixpeek.com；测试环境：https://server-xb24.onrender.com
• MIXPEEK_OPENAPI_URL：默认为 <API_BASE>/openapi.json（或 /docs/openapi.json）
• MCP_RATE_MAX_CALLS / MCP_RATE_PER_SECONDS：简单的令牌桶
• MCP_CONNECT_TIMEOUT / MCP_READ_TIMEOUT：请求超时

工作原理

• 加载 OpenAPI 规范，并使用 operationId 将 GET/POST JSON 端点映射为工具
• 工具参数接受顶层查询参数，或 query/body 封装对象
• 使用配置的标头将请求转发到 Mixpeek
• 提供小型允许列表（可配置），并在日志中对密钥进行脱敏

测试

单元测试：

pip install -r requirements.txt
pytest -q

实时测试（可选）：

export LIVE_MIXPEEK_API_KEY=sk_...
export LIVE_MIXPEEK_OPENAPI_URL=https://server-xb24.onrender.com/docs/openapi.json
export LIVE_MIXPEEK_API_BASE=https://server-xb24.onrender.com
pytest -q tests/test_live_integration.py

与 MCP 客户端配合使用

• 此服务使用 MCP stdio 传输和官方服务接口，兼容常见的 MCP 客户端。
• 启动服务，然后将 MCP 客户端指向 stdio 命令（mixpeek-mcp）。

参考资料

• Mixpeek 文档：https://docs.mixpeek.com/overview/introduction
• Mixpeek OpenAPI：https://api.mixpeek.com/docs/openapi.json
• MCP 概览：https://modelcontextprotocol.io/docs/getting-started/intro

备注

• 对于生产环境托管，请在前端配置 HTTPS，并添加 SSO/会话签发、按租户设置速率限制，以及不记录请求正文和标头的审计日志。默认使用本地 stdio；之后可添加托管 HTTP/SSE。