AI导哈

AI搜索智能协议服务器

DemandSphere MCP Server是一个连接AI助手与搜索智能平台的协议服务器，支持传统搜索引擎结果页分析(SERP)和生成式AI可见性跟踪。

  • by DemandSphereDev
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 DemandSphereDev/demandsphere-mcp

使用说明

DemandSphere MCP服务器

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

它的作用

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

域 工具 API版本
网站发现 list_sites, list_sites_flat v5.0
SERP分析 serp_analytics （视图：性能、趋势、工程比较、工程总结）， get_keyword_groups, get_local_rankings, get_landing_matches, get_landings_history v5.0
GenAI可见性 get_mentions, get_keyword_citations, get_bulk_citations, get_site_citations, llm_analytics （视图：统计数据、性能、频道、cross_channel、cross_llms）， get_llm_filters, get_people_also_ask v5.1
品牌管理 list_brands, create_brand, update_brand, delete_brands v5.1
ChatGPT深度研究 search, fetch compat

快速开始

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

安全模型

运输方式

运输 用例 安全边界
标准 本地（克劳德代码、游标） OS进程隔离；无网络暴露
流式HTTP 自托管/远程 HTTPS通过反向代理

API密钥处理

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

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

方法 最适合
环境变量 本地开发，CI/CD
配置文件(~/.config/demandsphere/) 个人机器
.env 文件 本地开发

自我寄宿

您可以在任何支持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_API_KEY （stdio必需） DemandSphere API键
DEMANDSPHERE_BASE_URL https://api.demandsphere.com API基本URL
DEMANDSPHERE_TRANSPORT stdio stdio 或 streamable-http
DEMANDSPHERE_HOST 127.0.0.1 HTTP服务器绑定地址
DEMANDSPHERE_PORT 8765 HTTP服务器端口
DEMANDSPHERE_REQUEST_TIMEOUT 30.0 HTTP超时（秒）
DEMANDSPHERE_MAX_REQUESTS_PER_MINUTE 60 利率上限
DEMANDSPHERE_MAX_RESULTS_PER_TOOL_CALL 100 每次响应的最大行数

项目结构

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/

升级

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

  • 观看发布 上 GitHub 收到新版本的通知
  • 拉最新 然后重新安装：
    git pull
uv sync     # or: pip install -e .
  • 看 更改日志.md 每次发布都有什么变化

许可证

麻省理工学院

文档

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

相关 MCP