Taranis MCP Server

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

Configuration

You need a reachable Taranis instance and a user with ASSESS_ACCESS. 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.

Installation 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.

PyPI with uvx

This option installs and runs the package without cloning the repository. Install uv, then add the following definition to a client that uses the mcpServers format, such as Claude Desktop or 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"
      }
    }
  }
}

Use which uvx on Linux/macOS or where uvx on Windows to find the executable. On Windows the path may end in uvx.exe. An absolute path is recommended because desktop applications may have a smaller PATH than an interactive shell.

Container with Docker

This option requires only Docker. On Windows, install and start Docker Desktop before launching the MCP client. The client passes its configured environment variables to docker, and the -e arguments forward them into the container:

{
  "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"
      }
    }
  }
}

The stable tag follows the newest stable container release. Replace it with an exact tag such as 0.1.1 for a reproducible installation. Likewise, append a version to the PyPI argument, such as taranis-mcp-server==0.1.1, to pin that installation.

For either installation method, use a JWT by replacing the username and password with TARANIS_ACCESS_TOKEN. In the Docker arguments, also replace the two credential -e entries with "-e", "TARANIS_ACCESS_TOKEN".

MCP Registry

Starting with version 0.1.1, releases are published as io.github.taranis-ai/taranis-mcp-server in the official MCP Registry. Registry-aware applications can use that identity to discover the server and choose either its PyPI or OCI package. The registry does not define one universal install command, so the final confirmation and configuration flow depends on the application.

Do not commit a project-level MCP configuration containing credentials. Restart or reload the client after saving its configuration. Its MCP settings should show a taranis server with the list_stories and list_sources tools. 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 and the Codex IDE extension share MCP configuration from ~/.codex/config.toml. Add this server definition, replacing the absolute path:

[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"

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 and list_sources. 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-server

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 from Source

Development requires Python 3.12 or newer and uv. Clone the repository, copy .env.example to .env, and install the locked dependencies:

uv sync --frozen

Run the server using the configuration from .env:

uv run --frozen taranis-mcp-server

Run the development checks:

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