Demandsphere MCP

DemandSphere MCP服务器

MCP（模型上下文协议）服务器，将AI助手连接到DemandSphere搜索智能平台。支持传统SERP分析（v5.0）和GenAI可见性跟踪（v5.1）。

它的作用

此服务器公开 20工具 跨越五个领域：

快速开始

1.安装

紫外线（推荐）：

git clone https://github.com/DemandSphereDev/demandsphere-mcp.git
cd demandsphere-mcp
uv sync

使用pip：

git clone https://github.com/DemandSphereDev/demandsphere-mcp.git
cd demandsphere-mcp
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

2.配置API密钥

选择一种方法：

# Option A: Environment variable
export DEMANDSPHERE_API_KEY="your-api-key"

# Option B: Config file
mkdir -p ~/.config/demandsphere
echo '{"api_key": "your-api-key"}' > ~/.config/demandsphere/config.json

# Option C: .env file in project root
echo 'DEMANDSPHERE_API_KEY=your-api-key' > .env

3.跑步

紫外线：

# stdio (default — for Claude Code, Claude Desktop, Cursor)
uv run demandsphere-mcp

# HTTP (for hosted/remote deployment)
DEMANDSPHERE_TRANSPORT=streamable-http uv run demandsphere-mcp

使用pip（安装后）：

# stdio
demandsphere-mcp

# HTTP
DEMANDSPHERE_TRANSPORT=streamable-http demandsphere-mcp

4.连接到您的MCP客户端

克劳德桌面/光标 --添加到您的MCP配置中：

紫外线：

{
  "mcpServers": {
    "demandsphere": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/demandsphere-mcp", "demandsphere-mcp"],
      "env": {
        "DEMANDSPHERE_API_KEY": "your-api-key"
      }
    }
  }
}

与pip（之后 pip install -e .):

{
  "mcpServers": {
    "demandsphere": {
      "command": "demandsphere-mcp",
      "env": {
        "DEMANDSPHERE_API_KEY": "your-api-key"
      }
    }
  }
}

克劳德代码：

claude mcp add demandsphere \
  -e DEMANDSPHERE_API_KEY=your-api-key \
  -- uv run --directory /path/to/demandsphere-mcp demandsphere-mcp

安全模型

运输方式

API密钥处理

DemandSphere API使用query-parameter-auth。MCP服务器持有密钥并将其注入到每个出站请求中。人工智能模型永远看不到关键。

重要提示： 由于API密钥在URL查询字符串中，因此它可能会出现在反向代理访问日志、CDN日志或网络监控工具中。如果部署在反向代理后面，请将其配置为从访问日志中删除或编辑查询字符串。

自我寄宿

您可以在任何支持Docker或Python的平台上自行部署MCP服务器：

Docker：

docker build -t demandsphere-mcp .
docker run -p 127.0.0.1:8765:8765 \
  -e DEMANDSPHERE_API_KEY=your-api-key \
  demandsphere-mcp

服务器位于 http://localhost:8765/mcp。与Cloudflare Workers、Railway、Fly.io、Northflange、Render、Google Cloud Run、AWS Fargate或任何容器平台兼容。A. docker-compose.yml 包含在生产硬化中（cap_drop、只读、非根）。

没有Docker：

DEMANDSPHERE_TRANSPORT=streamable-http \
DEMANDSPHERE_HOST=0.0.0.0 \
DEMANDSPHERE_API_KEY=your-api-key \
demandsphere-mcp

将HTTPS反向代理（Caddy、nginx、Cloudflare Tunnel）放在前面以供生产使用。

速率限制

客户端令牌桶速率限制器（默认值：60 req/min）。响应整形将每次工具调用的结果集限制为100行，以保持LLM令牌成本可控。两者都可以通过环境变量进行配置。

配置参考

通过环境变量（前缀）进行所有设置 DEMANDSPHERE_):

项目结构

demandsphere-mcp/
├── pyproject.toml                          # Package config + deps
├── Dockerfile                              # Container deployment
├── docker-compose.yml                      # Production hardening example
├── CHANGELOG.md                            # Version history
├── CONTRIBUTING.md                         # Contribution guidelines
├── config.example.json                     # API key config example
├── examples/
│   ├── mcp-config-uv.json                 # MCP client config (uv)
│   └── mcp-config-pip.json                # MCP client config (pip)
├── tests/
│   ├── test_core.py                       # Unit tests (validators, shaping, errors)
│   ├── test_hints.py                      # Hint builder tests
│   ├── test_brands.py                     # Brand dry_run tests
│   ├── test_consolidated.py               # serp_analytics + llm_analytics tests
│   ├── test_prompts.py                    # MCP Prompt tests
│   └── test_resources.py                  # MCP Resource tests
└── src/demandsphere_mcp/
    ├── __init__.py
    ├── py.typed                            # PEP 561 type marker
    ├── server.py                           # MCP server entry point
    ├── config.py                           # Settings (env vars + config file)
    ├── client.py                           # Async HTTP client + rate limiter
    └── tools/
        ├── __init__.py
        ├── utils.py                        # Error handling, validation, hints
        ├── sites.py                        # Site discovery (v5.0)
        ├── keywords_v50.py                 # SERP analytics (v5.0)
        ├── genai_v51.py                    # GenAI visibility (v5.1)
        ├── brands_v51.py                   # Brand management (v5.1)
        ├── chatgpt_compat.py              # ChatGPT Deep Research (search/fetch)
        ├── prompts.py                     # MCP Prompts (workflow templates)
        └── resources.py                   # MCP Resources (parameter discovery)

发展

# With uv
uv sync --extra dev
uv run pytest
uv run ruff check src/
uv run mcp dev src/demandsphere_mcp/server.py

# With pip
pip install -e ".[dev]"
pytest
ruff check src/

升级

此项目使用 语义化版本。要了解最新信息：

• 观看发布 上 收到新版本的通知
• 拉最新 然后重新安装：

  git pull
  uv sync     # or: pip install -e .

• 看 更改日志.md 每次发布都有什么变化

许可证

麻省理工学院

文档

其他文档，包括API指南、用例示例和集成演练，可在 DemandSphere帮助中心 （需要登录）。