DemandSphere Server

An MCP (Model Context Protocol) server that connects AI assistants to the DemandSphere search intelligence platform. Supports both traditional SERP analytics (v5.0) and GenAI visibility tracking (v5.1).

What It Does

This server exposes 20 tools across five domains:

Domain	Tools	API Version
Site Discovery	list_sites, list_sites_flat	v5.0
SERP Analytics	serp_analytics (views: performance, trends, engine_comparison, engine_summary), get_keyword_groups, get_local_rankings, get_landing_matches, get_landings_history	v5.0
GenAI Visibility	get_mentions, get_keyword_citations, get_bulk_citations, get_site_citations, llm_analytics (views: stats, performance, channels, cross_channel, cross_llms), get_llm_filters, get_people_also_ask	v5.1
Brand Management	list_brands, create_brand, update_brand, delete_brands	v5.1
ChatGPT Deep Research	search, fetch	compat

Quick Start

1. Install

With uv (recommended):

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

With 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. Configure API Key

Choose one method:

# 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. Run

With uv:

# 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

With pip (after install):

# stdio
demandsphere-mcp

# HTTP
DEMANDSPHERE_TRANSPORT=streamable-http demandsphere-mcp

4. Connect to Your MCP Client

Claude Desktop / Cursor — add to your MCP config:

With uv:

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

With pip (after pip install -e .):

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

Claude Code:

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

Security Model

Transport Modes

Transport	Use Case	Security Boundary
stdio	Local (Claude Code, Cursor)	OS process isolation; no network exposure
Streamable HTTP	Self-hosted / remote	HTTPS via reverse proxy

API Key Handling

The DemandSphere API uses query-parameter auth. The MCP server holds the key and injects it into every outbound request. The AI model never sees the key.

Important: Because the API key is in the URL query string, it may appear in reverse proxy access logs, CDN logs, or network monitoring tools. If deploying behind a reverse proxy, configure it to strip or redact query strings from access logs.

Method	Best For
Environment variable	Local dev, CI/CD
Config file (~/.config/demandsphere/)	Personal machines
.env file	Local dev

Self-Hosting

You can deploy the MCP server yourself on any platform that supports Docker or Python:

Docker:

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

The server is available at http://localhost:8765/mcp. Works with Cloudflare Workers, Railway, Fly.io, Northflank, Render, Google Cloud Run, AWS Fargate, or any container platform. A docker-compose.yml is included with production hardening (cap_drop, read_only, non-root).

Without Docker:

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

Put an HTTPS reverse proxy (Caddy, nginx, Cloudflare Tunnel) in front for production use.

Rate Limiting

Client-side token-bucket rate limiter (default: 60 req/min). Response shaping caps result sets at 100 rows per tool call to keep LLM token costs manageable. Both are configurable via environment variables.

Configuration Reference

All settings via environment variables (prefix DEMANDSPHERE_):

Variable	Default	Description
DEMANDSPHERE_API_KEY	(required for stdio)	DemandSphere API key
DEMANDSPHERE_BASE_URL	https://api.demandsphere.com	API base URL
DEMANDSPHERE_TRANSPORT	stdio	stdio or streamable-http
DEMANDSPHERE_HOST	127.0.0.1	HTTP server bind address
DEMANDSPHERE_PORT	8765	HTTP server port
DEMANDSPHERE_REQUEST_TIMEOUT	30.0	HTTP timeout (seconds)
DEMANDSPHERE_MAX_REQUESTS_PER_MINUTE	60	Rate limit cap
DEMANDSPHERE_MAX_RESULTS_PER_TOOL_CALL	100	Max rows per response

Project Structure

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)

Development

# 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/

Upgrades

This project uses semantic versioning. To stay up to date:

• Watch releases on GitHub to be notified of new versions
• Pull latest and re-install:

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

• See CHANGELOG.md for what changed in each release

License

MIT

Documentation

Additional documentation including API guides, use case examples, and integration walkthroughs is available at the DemandSphere Help Center (login required).