simpletel

simpletel-mcp

适用于 simpletel 的模型上下文协议服务 — 询问你的 编码 Agent “刚才发生了什么？”，让它读取你正在运行的服务的 OpenTelemetry 跟踪记录、 日志、指标和账户用量。

simpletel mcp 是内置于 simpletel CLI 的 stdio MCP 服务。它通过 stdin/stdout 使用以换行符分隔的 JSON-RPC 2.0（MCP 协议修订版 2025-06-18），并将 simpletel 的读取命令作为原生 Agent 工具提供。 它是单个静态二进制文件：无需运行时、无依赖、无后台服务。

• 一行命令安装 CLI：curl -fsSL https://simpletel.dev/install | sh
• 运行命令：simpletel mcp
• 或使用容器：ghcr.io/willnewby/simpletel-mcp
• 注册表名称：io.github.willnewby/simpletel

---

工具

该服务提供四种工具。每种工具都返回文本（对应 CLI 命令生成的 JSON 文档）；工具端的失败会作为带有 isError: true 的普通结果返回 — 工具调用不会中断会话。

工具	参数	功能
get_traces	since（默认值为 1h）、service、errors_only、min_duration、limit	按时间从新到旧列出此团队的跟踪记录。即 simpletel get traces --format json 生成的 JSON 文档。可用于查找失败或缓慢的请求。
get_trace	trace_id（必需）	获取一条完整的跟踪记录 — 包含 span、span 事件和关联的日志记录。即 simpletel get trace <id> --format json 生成的 JSON 文档。
verify	service（必需）、timeout（默认值为 60s）	运行 simpletel verify 入门检查：持续轮询，直到 service 出现一条包含库自动插桩 span 的新跟踪记录。返回阶段报告和退出状态（0 表示验证通过，1 表示超时）。超时表示检查已完成，并非工具错误。
usage	（无）	显示账户的套餐、本月至今的记录数、配额和消费上限。即 simpletel usage --format json 生成的 JSON 文档。按账户范围查询（需要已登录用户令牌）。

get_traces、get_trace 和 verify 按团队范围查询；usage 按账户范围查询。

---

身份验证和团队解析

服务在启动时解析一次连接，所用优先级与其他所有 simpletel 读取命令相同：**标志 > 环境变量 > 配置文件

默认值**。

设置	标志	环境变量	配置文件	默认值
端点	--endpoint	SIMPLETEL_ENDPOINT	endpoint	http://localhost:4318
团队	--team	SIMPLETEL_TEAM	current_team	（无）
管理员令牌	--admin-token	SIMPLETEL_ADMIN_TOKEN	—	（无）
用户令牌（用于 usage）	—	SIMPLETEL_TOKEN	auth token	（无）
配置路径	--config	SIMPLETEL_CONFIG	—	~/.simpletel/config.toml

• 配置文件位于 ~/.simpletel/config.toml，由 simpletel login 和 simpletel team 写入（模式为 0600）。simpletel login 会使用 GitHub 为你登录；simpletel team create / simpletel team use 用于设置当前团队。
• --team 接受 20 位十六进制团队 ID — 按原样使用，无需令牌 — 或者接受易记名称。名称只会被解析，不会创建，且需要管理员令牌才能查询。
• usage 还需要用户令牌：运行 simpletel login，或设置 SIMPLETEL_TOKEN（stk_… 令牌）。

如果团队缺失或不正确，服务仍会响应 initialize 和 tools/list，因此客户端可以看到工具目录；之后每次按团队范围查询的调用都会将问题作为其自身的 isError 结果返回。

此服务除工具向你配置的端点发出的读取请求外，绝不会向 simpletel 发送任何内容。诊断信息会写入 stderr；stdout 仅承载协议消息。

---

安装

1. 安装 CLI

curl -fsSL https://simpletel.dev/install | sh

将 simpletel 安装到 ~/.simpletel/bin/（验证 sha256；无需 sudo， 绝不会提示确认）。然后登录并创建或选择团队：

simpletel login            # GitHub device flow
simpletel team create --name my-team

2. 将服务注册到客户端

MCP 子命令为 simpletel mcp。它接受连接标志 --endpoint、--team、--admin-token 和 --config。

Claude Code

# by 20-hex team id (no extra credentials needed)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp --team <20-hex-team-id>

# or rely on the logged-in config file (~/.simpletel/config.toml)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp

也可以通过 --env 将连接值作为环境变量传入：

claude mcp add simpletel \
  --env SIMPLETEL_ENDPOINT=https://simpletel.dev \
  --env SIMPLETEL_TEAM=<20-hex-team-id> \
  -- ~/.simpletel/bin/simpletel mcp

Claude Desktop / 任何使用 JSON 配置的客户端（claude_desktop_config.json、 Cursor、Cline、Windsurf 等）：

{
  "mcpServers": {
    "simpletel": {
      "command": "/Users/you/.simpletel/bin/simpletel",
      "args": ["mcp"],
      "env": {
        "SIMPLETEL_ENDPOINT": "https://simpletel.dev",
        "SIMPLETEL_TEAM": "<20-hex-team-id>"
      }
    }
  }
}

如果你已在本地登录，可以省略 env，此时 command 会读取 ~/.simpletel/config.toml。如果客户端运行在无法读取主目录的沙盒中，请改用 env（或对应的 --env / --router 参数）传入这些值。

---

Docker

此镜像包含 CLI，并运行 simpletel mcp。它支持 linux/amd64 和 linux/arm64：

docker run -i --rm ghcr.io/willnewby/simpletel-mcp:latest

容器启动时不包含任何凭据。你可以通过挂载配置文件或使用环境变量提供凭据（推荐，镜像中不会写入任何内容）。

挂载现有配置文件（只读）。镜像以 distroless nonroot 用户（uid/gid 65532）运行，且 HOME=/home/nonroot，因此 CLI 在容器内的默认 配置路径为 /home/nonroot/.simpletel/config.toml。 由于 simpletel login 会将该文件的权限设为 0600，请以文件所有者身份运行容器，以确保文件仍可读取：

docker run -i --rm \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/.simpletel/config.toml:/home/nonroot/.simpletel/config.toml:ro" \
  ghcr.io/willnewby/simpletel-mcp:latest

（通过下方的 -e 传入连接信息即可完全避免所有权问题，也是推荐的方式。）

或者通过环境变量传入所有信息：

docker run -i --rm \
  -e SIMPLETEL_ENDPOINT=https://simpletel.dev \
  -e SIMPLETEL_TEAM=<20-hex-team-id> \
  ghcr.io/willnewby/simpletel-mcp:latest

作为 JSON 客户端条目：

{
  "mcpServers": {
    "simpletel": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SIMPLETEL_ENDPOINT=https://simpletel.dev",
        "-e", "SIMPLETEL_TEAM=<20-hex-team-id>",
        "ghcr.io/willnewby/simpletel-mcp:latest"
      ]
    }
  }
}

MCP 传输方式为 stdio，因此必须使用 -i（保持标准输入打开），且不得添加 -t。

---

配置参考

simpletel mcp [--endpoint URL] [--team <id-or-name>] [--admin-token TOKEN] [--config PATH]

变量	用途
SIMPLETEL_ENDPOINT	服务基础 URL——不带 /v1/traces 后缀（默认值为 http://localhost:4318）。
SIMPLETEL_TEAM	20 位十六进制团队 ID，或易读名称（使用名称时需要管理员令牌）。
SIMPLETEL_ADMIN_TOKEN	用于解析团队名称的令牌；使用 20 位十六进制 ID 时不需要。
SIMPLETEL_TOKEN	用户令牌（stk_…），供 usage 工具使用。
SIMPLETEL_CONFIG	配置文件路径（默认值为 ~/.simpletel/config.toml）。

---

限制

• 仅支持 stdio。 simpletel mcp 由客户端作为子进程启动；它不是 HTTP/SSE 端点。
• 只读。 这些工具会查询追踪记录、用量和引导状态，不会采集数据或更改账户设置。
• 除非使用容器，否则必须安装主机 CLI。 simpletel 二进制文件由 Dockerfile 在构建时获取；仓库本身不包含二进制文件——构建方式请参阅 Dockerfile。
• Windows 并非单行安装程序的正式支持目标；请使用 Docker 镜像或 WSL。

---

仓库内容

文件	用途
Dockerfile	根据已发布的 CLI 构建 stdio 镜像。
server.json	Official MCP Registry 清单（OCI 包）。CI 会在发布时重写版本号/标签。
glama.json	供 Glama 自动索引使用的维护者元数据。
llms-install.md	面向大模型 Agent / 目录爬虫的安装说明。
.github/workflows/publish.yml	构建并推送 ghcr.io/willnewby/simpletel-mcp，并发布到注册表。

许可证

MIT——详见 LICENSE。