传感器塔MCP服务器
一个MCP服务器，允许代理使用Sensor Tower API进行广告、市场和实用程序数据，不需要自定义HTTP客户端。
特性
- 基于FastMCP的MCP服务器，具有结构化工具注册功能。
- 涵盖应用分析、市场分析、商店营销、使用智能和实用端点。
- 针对常见参数问题（如广告网络别名）的内置输入规范化。
- 捆绑的OpenAPI规范(
swaggerdocs/)供参考和验证。
需求
- Python 3.10+
- API传感器塔代币(
SENSOR_TOWER_API_TOKEN环境变量） - （可选）备份API令牌(
SENSOR_TOWER_API_TOKEN_BACKUP用于自动故障转移） - （可选）Docker用于基于容器的部署
快速开始
- 安装依赖项和软件包：
uv sync # or: pip install -e .[test]- 导出API令牌：
export SENSOR_TOWER_API_TOKEN="st_xxxxxxxxx"
# Optional: Add backup token for automatic failover
export SENSOR_TOWER_API_TOKEN_BACKUP="st_yyyyyyyyy"- 启动MCP服务器：
python -m sensortower_mcp.serverFastMCP CLI将向您的编排器公开注册的工具。
自动令牌故障转移
当主令牌的配额用完时，服务器支持自动故障转移到备份API令牌：
- 集
SENSOR_TOWER_API_TOKEN_BACKUP带有备份令牌的环境变量 - 当主令牌达到速率限制（429）或配额错误（403）时，服务器会自动切换到备份令牌
- 开关记录有：
⚠️ Switching to backup token #2 - 所有后续请求都将使用备份令牌，直到服务器重新启动
这确保了即使一个API密钥达到其配额限制，服务也不会中断。
客户端设置（Cursor、Claude、Docker）
光标
- 设置→ MCP → 添加服务器→ 命令：
- 命令： python - 论据： -m sensortower_mcp.server - 环境：套 SENSOR_TOWER_API_TOKEN （以及可选 SENSOR_TOWER_API_TOKEN_BACKUP)
JSON示例（如果Cursor请求块）：
{
"name": "sensortower",
"command": "python",
"args": ["-m", "sensortower_mcp.server"],
"env": {
"SENSOR_TOWER_API_TOKEN": "st_xxxxxxxxx",
"SENSOR_TOWER_API_TOKEN_BACKUP": "st_yyyyyyyyy"
}
}Claude（桌面/带MCP的网络）
- 在设置中添加自定义MCP服务器→ 集成→ 模型上下文协议。
- 使用与上述相同的命令/args/env。
一些客户端接受的最小配置片段：
{
"mcpServers": {
"sensortower": {
"command": "python",
"args": ["-m", "sensortower_mcp.server"],
"env": {
"SENSOR_TOWER_API_TOKEN": "st_xxxxxxxxx",
"SENSOR_TOWER_API_TOKEN_BACKUP": "st_yyyyyyyyy"
}
}
}
}码头工人
在本地构建并运行服务器容器：
docker build -t sensortower-mcp .
docker run --rm \
-e SENSOR_TOWER_API_TOKEN=st_xxxxxxxxx \
-e SENSOR_TOWER_API_TOKEN_BACKUP=st_yyyyyyyyy \
-p 8666:8666 \
sensortower-mcp或者使用Compose（使用 docker-compose.yml):
docker compose up -d然后像往常一样将MCP客户端指向本地命令，或指向 http://localhost:8666 如果您的客户端支持HTTP MCP传输。
HTTP调用快捷方式
当在没有JSON-RPC会话的情况下通过HTTP运行服务器时，将暴露的传统网关作为目标 /legacy/tools/invoke:
curl \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-X POST "http://localhost:8666/legacy/tools/invoke" \
-d '{
"tool": "get_creatives",
"arguments": {
"os": "ios",
"app_ids": "835599320",
"start_date": "2023-01-01",
"end_date": "2023-01-31",
"countries": "US",
"networks": "Instagram,Unity",
"ad_types": "video"
}
}'端点始终以以下方式响应 { "tool": "", "result": }.合并 Accept 标头是必需的，因为FastMCP的HTTP传输执行的内容协商需要两者 application/json 和 text/event-stream 出席；省略它可能会在某些客户端中产生406个错误。服务器自动扩展过于严格 Accept 来自已知MCP客户端的值，但外部工具应显式设置标头以避免回归问题。
用法示例
从FastMCP调用创意工具需要 ad_types 参数，传感器塔将其标记为必填项：
from fastmcp import FastMCP
from sensortower_mcp.server import build_server
mcp = FastMCP("sensortower")
server = build_server(api_token="st_xxxxxxxxx")
server.register(mcp)
result = mcp.invoke_tool(
"get_creatives",
{
"os": "ios",
"app_ids": "284882215",
"start_date": "2024-01-01",
"countries": "US",
"networks": "Instagram",
"ad_types": "video"
}
)测试
安装测试附加组件，并使用 uv （首选）或主动virtualenv：
uv sync --extra test
uv run pytest tests/test_result_normalization.py # fast structural sanity check
uv run pytest # full offline suiteAPI现场练习标有 @pytest.mark.live_api 并要求有效 SENSOR_TOWER_API_TOKEN。仅使用以下命令执行该套件：
uv run pytest -m live_apiMCP服务器必须在本地运行（请参阅快速入门），HTTP调用者应发送 Accept: application/json, text/event-stream--或者使用传统网关，当已知的MCP客户端连接时，它会自动对报头进行标准化。
击中已部署包或原始MCP传输的手动烟雾脚本已被移动到 manual/。它们不是自动化CI的一部分，但仍可用于特殊验证：
manual/search_entities_fix.py–验证已发布包的search_entities帮手。manual/search_entities_mcp.py–端到端JSON-RPC烟雾测试search_entities.
运行它们 python manual/.py；每个脚本打印一个摘要并相应地退出0/1。
看 docs/testing.md 获取完整的测试矩阵、CI建议和故障排除提示。
发布亮点
- 1.2.10：使用元数据驱动的使用提示扩展工具文档字符串，使MCP客户端无需额外手动编辑即可显示示例和注释。
- 1.2.1：确保
get_creatives转发所需ad_types查询参数，阻止来自传感器塔的422个响应。添加回归覆盖率，以便在发布前检测缺失的参数。
贡献
欢迎提出问题和合并请求。请在自述和 README-pypi.md 同步。