使用说明

Things Stack MCP服务器

MCP（模型上下文协议）服务器事物堆叠 HTTP API。该服务器支持通过标准化的MCP工具与The Things Industries LoRaWAN平台进行交互。

特性

MCP服务器提供了一系列用于管理LoRaWAN基础设施的工具：

应用程序管理：创建、列出、删除和检查应用程序。
设备管理：全面的设备生命周期管理，包括 create_otaa_device 它一次性处理身份、加入、网络和应用程序服务器之间的注册。
网关管理：列出、检查、创建和删除网关。
用户管理：检索用户详细信息。
Webhook集成：管理用于应用程序与外部系统集成的webhooks。
消息传递：查看历史上行链路、模拟上行链路和管理下行链路队列。
有效载荷格式化程序：生成命令以配置格式化程序或直接对其进行测试。

先决条件

已安装Docker和Docker Compose
帐户在事物堆叠或私有实例
具有适当权限的API密钥

创建API密钥

登录到 Things Stack控制台
转到您的用户设置（个人资料）
引导到 API密钥
点击 添加API密钥
为其命名（例如，“MCP服务器”）
选择以下权限：
- 应用：读写
- 设备：读写
- 网关：读写
- 用户：阅读
复制生成的API密钥（格式： NNSXS.XXX...)

快速开始

# 1. Build Docker Image
docker build -t things-stack-mcp .

# 2. Test (replace placeholder values!)
export TTS_BASE_URL=https://eu1.cloud.thethings.network
export TTS_API_KEY=NNSXS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
./test_server.sh

安装和设置

1.克隆存储库/创建文件

确保项目目录中存在所有文件：

├── server.py                            # MCP Server Implementation
├── requirements.txt                     # Python Dependencies
├── Dockerfile                           # Docker Image Definition
├── docker-compose.yml                   # Docker Compose Configuration
├── claude_desktop_config.example.json   # Claude Desktop Example Config
├── test_server.sh                       # Test Script
├── run_example.sh                       # Interactive Start Script
└── README.md                            # This file

2.构建Docker镜像

docker build -t things-stack-mcp .

3.配置

可用区域：

欧洲： https://eu1.cloud.thethings.network
北美： https://nam1.cloud.thethings.network
澳大利亚： https://au1.cloud.thethings.network
私有实例： https://your-instance.example.com

环境变量直接在Docker run命令中传递（见下一节）。

用法

与MCP兼容的客户端

服务器可以与任何兼容MCP的客户端（例如Claude Desktop App）一起使用。

Claude桌面配置

将以下内容添加到您的Claude Desktop配置中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "things-stack": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TTS_BASE_URL=https://eu1.cloud.thethings.network",
        "-e",
        "TTS_API_KEY=NNSXS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "things-stack-mcp"
      ]
    }
  }
}

重要提示： 替换 NNSXS.XXX... 使用您的实际API键，并在必要时调整区域。

提示： 你可以使用 claude_desktop_config.example.json 作为模板。

交互式开始

使用交互式脚本进行简单配置：

./run_example.sh

脚本将询问您的区域和API密钥，然后启动服务器。

Docker直接测试

# Start server interactively
docker run --rm -i \
  -e TTS_BASE_URL=https://eu1.cloud.thethings.network \
  -e TTS_API_KEY=NNSXS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
  things-stack-mcp

# Example: List Applications
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_applications","arguments":{}},"id":1}' | \
docker run --rm -i \
  -e TTS_BASE_URL=https://eu1.cloud.thethings.network \
  -e TTS_API_KEY=NNSXS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
  things-stack-mcp

例子

创建应用

{
  "name": "create_application",
  "arguments": {
    "user_id": "your-user-id",
    "application_id": "my-app",
    "name": "My Application",
    "description": "Test Application"
  }
}

创建OTAA设备（推荐）

{
  "name": "create_otaa_device",
  "arguments": {
    "application_id": "my-app",
    "device_id": "my-device-01",
    "name": "Sensor 01",
    "description": "Temperature sensor in office",
    "dev_eui": "70B3D57ED0000001",
    "join_eui": "0000000000000000",
    "app_key": "00112233445566778899AABBCCDDEEFF",
    "lorawan_version": "MAC_V1_0_3",
    "frequency_plan_id": "EU_863_870_TTN",
    "supports_class_c": false
  }
}

此工具执行 4个单独的API调用 在所有必需的服务器上注册设备：

发布 /api/v3/applications/{app_id}/devices -身份服务器
- 元数据（名称、ID、描述）
- 服务器地址
放 /api/v3/js/applications/{app_id}/devices/{device_id} -加入服务器
- 根密钥（OTAA的AppKey）
- 认证
放 /api/v3/ns/applications/{app_id}/devices/{device_id} -网络服务器
- MAC设置
- LoRaWAN版本和物理层版本
- 频率计划
- B/C类支持
放 /api/v3/as/applications/{app_id}/devices/{device_id} -应用服务器
- 设备ID
- 会话配置

重要参数：

app_key：32位十六进制字符串（128位密钥）
dev_eui & join_eui：16位十六进制字符串（64位）
frequency_plan_id：常见值：
- EU_863_870_TTN -欧洲（默认）
- US_902_928 -美国
- AU_915_928 -澳大利亚
- AS_923 -亚洲
lorawan_version: MAC_V1_0_2, MAC_V1_0_3, MAC_V1_0_4, MAC_V1_1

创建Webhook

{
  "name": "set_webhook",
  "arguments": {
    "application_id": "my-app",
    "webhook_id": "my-integration",
    "base_url": "https://myserver.com/webhook",
    "format": "json",
    "uplink_message": {
      "path": "/up"
    },
    "join_accept": {
      "path": "/join"
    }
  }
}

设置有效载荷格式化程序（命令生成器）

{
  "name": "generate_formatter_command",
  "arguments": {
    "application_id": "my-app",
    "device_id": "my-device-01",
    "formatter_type": "FORMATTER_JAVASCRIPT",
    "formatter_code": "function decodeUplink(input) { return {data: {temp: input.bytes[0]}}; }",
    "command_type": "curl"
  }
}

输出： 已准备好使用cURL命令进行复制和执行。

可用命令类型：

curl -cURL命令（默认）
cli -Things Stack CLI命令
python -Python脚本

该工具生成 即用型命令 您可以直接执行，因为直接的API调用可能不适用于所有TTS安装。

检索上行链路数据

{
  "name": "get_device_uplinks",
  "arguments": {
    "application_id": "my-app",
    "device_id": "my-device-01",
    "limit": 20
  }
}

发展

没有Docker的本地开发

# Create Virtual Environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Dependencies
pip install -r requirements.txt

# Set Environment Variables
export TTS_BASE_URL=https://eu1.cloud.thethings.network
export TTS_API_KEY=NNSXS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Start Server
python server.py

故障排除

身份验证错误（401）

验证您的API密钥是否正确
确保API密钥具有所需的权限
检查API密钥是否仍然有效
API密钥应以开头 NNSXS.

连接错误

检查 TTS_BASE_URL （必须以 https://)
确保您使用的是正确的地区
检查您的网络连接
对于自托管实例：检查防火墙和SSL证书

设备创建失败

dev_eui 和 join_eui 必须是有效的64位十六进制字符串（16个字符）
device_id 只能包含小写字母、数字和破折号
应用程序必须已存在

Claude Desktop中的MCP服务器未启动

检查Claude Desktop配置中的JSON语法
确保Docker镜像已构建： docker build -t things-stack-mcp .
检查Docker日志： docker logs <container-id>

API参考资料

许可证

麻省理工学院

作者

使用Claude Code创建