sensortower

This MCP server provides a Sensor Tower integration for FastMCP, exposing tools to access App Analysis, Market Analysis, Store Marketing, Usage Intelligence, and various utility endpoints via the MCP protocol. Run the server locally (or in a container) with your Sensor Tower API token, then connect your MCP orchestrator or client to the server. The server registers a suite of tools that map to Sensor Tower API capabilities, including creatives retrieval, analytics-like data, and other utility endpoints, with input normalization to handle common parameter issues.

To use it, start the server using the Python module approach described in the Quick Start. Then configure your MCP client (Cursor, Claude, or your own HTTP RPC bridge) to point at the local host and port where the server exposes the MCP API (by default port 8666). Provide the same environment variable SENSOR_TOWER_API_TOKEN to authorize requests. You can invoke tools like get_creatives and related endpoints through the MCP transport, or via the HTTP legacy gateway at /legacy/tools/invoke if you’re issuing raw HTTP requests. The server includes an OpenAPI reference under swaggerdocs/ for validation and exploration of available tools and parameters.

Prerequisites:

• Python 3.10 or newer
• Access to Sensor Tower API with a valid token (SENSOR_TOWER_API_TOKEN)
• (Optional) Docker if you prefer containerized deployment

Install and run (local development):

1. Install dependencies and the package: uv sync # or: pip install -e .[test]

2. Export your API token: export SENSOR_TOWER_API_TOKEN="st_xxxxxxxxx"

3. Run the MCP server: python -m sensortower_mcp.server

If you want to run via Docker:

1. Build the image (Dockerfile assumed in repository): docker build -t sensortower-mcp .

2. Run the container with the token and port exposed: docker run --rm
   -e SENSOR_TOWER_API_TOKEN=st_xxxxxxxxx
   -p 8666:8666
   sensortower-mcp

3. Optional: use Docker Compose if provided (uses docker-compose.yml): docker compose up -d

Client configuration (example):

• Cursor or Claude users should point to the same command/args with the SENSOR_TOWER_API_TOKEN in env.
• For HTTP usage, connect to http://localhost:8666 and use the legacy gateway at /legacy/tools/invoke for direct tool invocations.

Note: Ensure the SENSOR_TOWER_API_TOKEN is kept secret and not committed to version control.

Tips and notes:

• Ensure the SENSOR_TOWER_API_TOKEN environment variable is set in all deployment environments (local, container, or orchestrator).
• The server exposes an OpenAPI specification under swaggerdocs/ for reference and validation of endpoints and parameters.
• When using the HTTP transport, clients should supply Accept: application/json, text/event-stream to avoid 406 errors due to content negotiation.
• If you see parameter-related 422/430 errors from Sensor Tower, verify inputs align with required fields (e.g., ad_types for creatives).
• If you rely on the legacy HTTP gateway, remember that tool invocation payloads should match the structure shown in the README examples.
• For testing local behavior, you can use uv sync with test extras (uv sync --extra test) and run pytest suites as documented.