Taranis AI

Taranis MCP 服务

面向 Taranis AI 的只读 Model Context Protocol 服务。当前版本通过 stdio 或经过身份验证的 Streamable HTTP 提供 list_stories 和 list_sources 工具。

配置

你需要一个可访问的 Taranis 实例，以及一个拥有 ASSESS_ACCESS 权限的用户。将 TARANIS_API_URL 设为完整的 API 根地址，包括 /api，然后选择且仅选择一种身份验证模式：

• TARANIS_USERNAME 和 TARANIS_PASSWORD：服务会按需登录，并可在 JWT 过期后重新登录。
• TARANIS_ACCESS_TOKEN：使用 Taranis /api/auth/login 返回的现有 JWT；没有凭据时无法续期。

不要将 Taranis JWT 重复用作 MCP_ACCESS_TOKEN。后者用于保护 MCP HTTP 端点，stdio 模式不需要它。

安装和 MCP 客户端配置

此服务面向桌面 AI 助手和开发者工具。支持 MCP 的桌面应用包括 Claude Desktop 和 OpenAI 的 ChatGPT 桌面应用。IDE 和终端客户端包括 Cursor、Zed、Codex CLI 和 Codex IDE 扩展。如果其他助手（例如 Mistral Le Chat）在你安装的版本或工作区中提供 MCP 集成，请根据情况使用其本地 stdio 或远程 Streamable HTTP 配置。

支持本地 stdio 的客户端可以将此服务作为子进程启动。配置文件的位置和外围架构取决于客户端，但服务命令、参数和环境相同。仅支持远程 MCP 连接器的桌面应用应使用下方的 Streamable HTTP 设置。

使用 uvx 从 PyPI 安装

此选项无需克隆仓库即可安装并运行软件包。先安装 uv，然后将以下定义添加到使用 mcpServers 格式的客户端中，例如 Claude Desktop 或 Cursor：

{
  "mcpServers": {
    "taranis": {
      "command": "/absolute/path/to/uvx",
      "args": ["taranis-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "TARANIS_API_URL": "https://taranis.example/api",
        "TARANIS_USERNAME": "analyst",
        "TARANIS_PASSWORD": "change-me"
      }
    }
  }
}

在 Linux/macOS 上使用 which uvx，或在 Windows 上使用 where uvx 查找可执行文件。在 Windows 上，路径可能以 uvx.exe 结尾。建议使用绝对路径，因为桌面应用的 PATH 可能比交互式 Shell 更短。

使用 Docker 容器

此选项只需要 Docker。在 Windows 上，启动 MCP 客户端之前，请先安装并启动 Docker Desktop。客户端会将配置的环境变量传递给 docker，而 -e 参数会将它们传入容器：

{
  "mcpServers": {
    "taranis": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TARANIS_API_URL",
        "-e",
        "TARANIS_USERNAME",
        "-e",
        "TARANIS_PASSWORD",
        "ghcr.io/taranis-ai/taranis-mcp-server:stable"
      ],
      "env": {
        "TARANIS_API_URL": "https://taranis.example/api",
        "TARANIS_USERNAME": "analyst",
        "TARANIS_PASSWORD": "change-me"
      }
    }
  }
}

stable 标签会跟随最新的稳定容器版本。为确保安装可复现，可将其替换为确切的标签，例如 0.1.1。同样，也可以在 PyPI 参数中附加版本号来固定安装版本，例如 taranis-mcp-server==0.1.1。

对于这两种安装方式，如需使用 JWT，请将用户名和密码替换为 TARANIS_ACCESS_TOKEN。在 Docker 参数中，也请将两个凭据 -e 条目替换为 "-e", "TARANIS_ACCESS_TOKEN"。

MCP Registry

从 0.1.1 版本开始，发布版本会以 io.github.taranis-ai/taranis-mcp-server 的名称发布到官方 MCP Registry。支持 Registry 的应用可以使用该标识来发现此服务，并选择其 PyPI 或 OCI 软件包。Registry 不会定义统一的安装命令，因此最终的确认和配置流程取决于具体应用。

不要提交包含凭据的项目级 MCP 配置。保存配置后，请重启或重新加载客户端。其 MCP 设置中应显示一个包含 list_stories 和 list_sources 工具的 taranis 服务。对于使用不同配置架构的客户端（例如 Zed），请将相同的命令、参数列表和环境值填入该客户端的 stdio MCP 定义中。

Codex

Codex CLI 和 Codex IDE 扩展共享 ~/.codex/config.toml 中的 MCP 配置。添加此服务定义，并替换绝对路径：

[mcp_servers.taranis]
command = "/absolute/path/to/uvx"
args = ["taranis-mcp-server"]
env_vars = ["TARANIS_USERNAME", "TARANIS_PASSWORD"]

[mcp_servers.taranis.env]
MCP_TRANSPORT = "stdio"
TARANIS_API_URL = "https://taranis.example/api"

启动 Codex 前，导出转发的凭据：

export TARANIS_USERNAME=analyst
export TARANIS_PASSWORD=change-me
codex mcp list
codex

在 Codex TUI 中使用 /mcp，确认 taranis 已启用并提供 list_stories 和 list_sources。若要改用 JWT，请将 env_vars 中的两个名称替换为 TARANIS_ACCESS_TOKEN，并导出该变量。

Streamable HTTP

对于单独运行的服务，配置 MCP_TRANSPORT=streamable-http，设置强度足够的 MCP_ACCESS_TOKEN，然后启动：

uv run --frozen taranis-mcp-server

默认端点为 http://127.0.0.1:8000/mcp。客户端必须发送 Authorization: Bearer <MCP_ACCESS_TOKEN>。对于非本地部署，请将 MCP_PUBLIC_URL、MCP_ISSUER_URL、MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS 配置为外部可见地址，并在受信任的反向代理处终止 TLS。

从源代码开发

开发需要 Python 3.12 或更高版本以及 uv。克隆代码仓库，将 .env.example 复制为 .env，然后安装锁定的依赖项：

uv sync --frozen

使用 .env 中的配置运行服务：

uv run --frozen taranis-mcp-server

运行开发检查：

uv run --frozen pytest
uv run --frozen ruff check .