Taranis MCP Server

A read-oriented Model Context Protocol server for Taranis AI. The current version exposes the list_stories tool over stdio or authenticated Streamable HTTP.

Requirements

• Python 3.12 or newer
• uv
• A reachable Taranis instance and a user with ASSESS_ACCESS

Install the locked dependencies:

uv sync --frozen

Configuration

Copy .env.example to .env for command-line use. Set TARANIS_API_URL to the complete API root, including /api, then choose exactly one authentication mode:

• TARANIS_USERNAME and TARANIS_PASSWORD: the server logs in lazily and can log in again after an expired JWT.
• TARANIS_ACCESS_TOKEN: use an existing JWT returned by Taranis /api/auth/login; it cannot be renewed without credentials.

Do not reuse a Taranis JWT as MCP_ACCESS_TOKEN. The latter protects the MCP HTTP endpoint and is not needed for stdio.

Desktop Apps and MCP Client Configuration

This server is intended for desktop AI assistants as well as developer tools. Desktop applications with MCP support include Claude Desktop and OpenAI's ChatGPT desktop app. IDE and terminal clients include Cursor, Zed, Codex CLI, and the Codex IDE extension. If another assistant, such as Mistral Le Chat, offers MCP integration in your installed version or workspace, use its local stdio or remote Streamable HTTP configuration as appropriate.

Clients that support local stdio can launch the server as a child process. The configuration file location and surrounding schema depend on the client, but the server command, arguments, and environment are the same. Desktop applications that support only remote MCP connectors should use the Streamable HTTP setup below instead.

Claude Desktop and Cursor support the following mcpServers definition directly. Add it to claude_desktop_config.json, a Cursor user-level MCP configuration, or .cursor/mcp.json, replacing the repository path, uv path, Taranis URL, and credentials:

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

Use which uv on Linux/macOS or where uv on Windows to find the executable. An absolute path is recommended because desktop applications may have a smaller PATH than an interactive shell. To use a JWT instead of username/password, replace both credential entries with "TARANIS_ACCESS_TOKEN": "replace-with-a-taranis-jwt".

Do not commit a project-level MCP configuration containing credentials; this repository ignores .cursor/mcp.json for that reason. Restart or reload the client after saving its configuration. Its MCP settings should show a taranis server with the list_stories tool. For clients such as Zed that use a different configuration schema, carry over the same command, argument list, and environment values into that client's stdio MCP definition.

Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration from ~/.codex/config.toml. Add this server definition, replacing both absolute paths:

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

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

Export the forwarded credentials before starting Codex:

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

Use /mcp inside the Codex TUI to confirm that taranis is active and exposes list_stories. To use a JWT instead, replace the two names in env_vars with TARANIS_ACCESS_TOKEN and export that variable.

Streamable HTTP

For a separately running server, configure MCP_TRANSPORT=streamable-http, set a strong MCP_ACCESS_TOKEN, and start:

uv run --frozen taranis-mcp

The default endpoint is http://127.0.0.1:8000/mcp. Clients must send Authorization: Bearer <MCP_ACCESS_TOKEN>. For a non-local deployment, configure MCP_PUBLIC_URL, MCP_ISSUER_URL, MCP_ALLOWED_HOSTS, and MCP_ALLOWED_ORIGINS for the externally visible address, and terminate TLS at a trusted reverse proxy.

Development checks

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