tracecat-mcp-community

A Model Context Protocol (MCP) server for the Tracecat SOAR platform — 49 tools across 12 domains.

What is this?

An MCP server that gives AI assistants (Claude Code, Claude Desktop, etc.) full control over a Tracecat instance through natural language. Manage workflows, actions, cases, secrets, tables, schedules, and more — without leaving your editor.

• 49 tools covering the full Tracecat API surface
• Lazy authentication — MCP transport starts instantly, login happens on first tool call
• Auto workspace detection — no manual workspace ID needed
• Session cookie auth — handles Tracecat's cookie-based auth transparently

Tools

| Domain | Tools | Description | |---|---|---| | Workflows | 9 | List, create, get, update, deploy, export, delete, validate, autofix | | Actions | 5 | List, create, get, update, delete workflow actions | | Executions | 5 | Run workflows, list/get/cancel executions, compact view | | Cases | 7 | List, create, get, update, delete cases; add/list comments | | Secrets | 5 | Search, create, get, update, delete secrets | | Tables | 5 | List, create, get, update, delete tables | | Columns | 2 | Create, delete table columns | | Rows | 6 | List, get, insert, update, delete, batch insert rows | | Schedules | 5 | List, create, get, update, delete schedules | | Graph | 3 | Add edges, move nodes, update trigger position | | Webhooks | 1 | Generate/rotate webhook API keys | | Docs | 2 | Search Tracecat docs, list available tool documentation | | Templates | 2 | List and get community workflow templates | | System | 1 | Health check |

Total: 49 tools for complete Tracecat automation.

Quick Start

Option A: npx (fastest)

# Install globally
npm install -g tracecat-mcp-community

Create a .env file wherever you run from (or in the package directory):

TRACECAT_API_URL=http://localhost/api
[email protected]
TRACECAT_PASSWORD=your-password-here
TRACECAT_WORKSPACE_ID=              # Optional — auto-detected if omitted

Add to your .mcp.json:

{
  "mcpServers": {
    "tracecat": {
      "command": "npx",
      "args": ["-y", "tracecat-mcp-community"]
    }
  }
}

Option B: From source

git clone https://github.com/adrojis/tracecat-mcp-community.git
cd tracecat-mcp-community
npm install
cp .env.example .env    # Edit with your credentials
npm run build

Add to your .mcp.json:

{
  "mcpServers": {
    "tracecat": {
      "command": "node",
      "args": ["/absolute/path/to/tracecat-mcp-community/dist/index.js"]
    }
  }
}

Option C: Docker

git clone https://github.com/adrojis/tracecat-mcp-community.git
cd tracecat-mcp-community
docker build -t tracecat-mcp-community .

{
  "mcpServers": {
    "tracecat": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "tracecat-mcp-community"]
    }
  }
}

Security: .env is gitignored and never committed. Never hardcode credentials in source files. See SECURITY.md.

Then restart Claude Code and verify with /mcp — you should see the tracecat server with 49 tools.

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | TRACECAT_API_URL | No | http://localhost/api | Tracecat API base URL | | TRACECAT_USERNAME | Yes | — | Login email | | TRACECAT_PASSWORD | Yes | — | Login password | | TRACECAT_WORKSPACE_ID | No | Auto-detected | Workspace ID (uses first workspace if omitted) |

Credentials are loaded from .env via dotenv. The .env file must be in the project root (next to package.json).

Architecture

src/
├── index.ts          # Entry point — StdioTransport + env loading
├── server.ts         # McpServer creation + tool registration
├── client.ts         # HTTP client with lazy auth + auto workspace injection
├── types.ts          # TypeScript interfaces
└── tools/
    ├── workflows.ts  # Workflow CRUD + deploy/export/validate/autofix
    ├── actions.ts    # Action CRUD with YAML inputs
    ├── cases.ts      # Case management + comments
    ├── executions.ts # Run, list, cancel, inspect executions
    ├── secrets.ts    # Secret management
    ├── tables.ts     # Tables, columns, and rows
    ├── graph.ts      # Graph operations (edges, node positions)
    ├── webhooks.ts   # Webhook key rotation
    ├── schedules.ts  # Cron/interval scheduling
    ├── docs.ts       # Documentation search
    ├── templates.ts  # Community workflow templates
    └── system.ts     # Health check

Key Design Decisions

| Decision | Rationale | |---|---| | Lazy initialization | MCP transport starts immediately; login happens on first tool call. Avoids blocking Claude Code startup. | | Session cookies | Tracecat currently uses fastapiusersauth cookies, not API keys. The client handles login and cookie extraction automatically. See note below on upcoming API token support. | | YAML string inputs | Action inputs are sent as YAML strings per the Tracecat API contract, not JSON objects. | | POST for updates | Actions, secrets, and schedules use POST for updates instead of the conventional PATCH. | | Auto workspace injection | workspace_id is auto-detected and injected as a query parameter on every request. | | Optimistic locking | Graph operations read base_version before patching to prevent concurrent edit conflicts. |

Authentication Roadmap

This server currently authenticates via username/password (session cookies). The Tracecat team is actively working on API token authentication, which will provide a simpler and more secure connection method — no more password in .env.

We will add API token support as soon as it becomes available upstream. The username/password method will remain supported for backward compatibility.

API Quirks

These behaviors differ from typical REST conventions and are handled transparently by the server:

| Quirk | Details | |---|---| | workspace_id as query param | Must be ?workspace_id=..., not a header | | POST for updates | /actions/{id}, /secrets/{id}, /schedules/{id} use POST | | Actions list endpoint | GET /actions?workflow_id=... (not nested under /workflows) | | Action inputs format | YAML string, not JSON object | | Workflow list pagination | Returns { items: [...], next_cursor }, not a plain array |

Development

# Watch mode (auto-reload)
npm run dev

# Build TypeScript
npm run build

# Run directly
node dist/index.js

Testing

npm run build
npm test

Tests use Node.js built-in test runner (no extra dependencies). See CONTRIBUTING.md for guidelines.

MCP Inspector

The MCP Inspector is a visual debugging tool that lets you browse and test all 49 tools interactively in your browser — useful for verifying your setup, exploring tool schemas, and testing API calls without Claude.

From the project root:

npx @modelcontextprotocol/inspector node dist/index.js

This starts a local web UI (default: http://localhost:6274). Click the Tools tab to see all available tools, inspect their input schemas, and execute them against your Tracecat instance.

Roadmap

This project is under active development. Tracecat's API surface evolves fast, and we intend to keep up — expect new tools, refinements, and breaking-change adaptations as the platform matures.

Planned areas of improvement:

• More tools — covering new Tracecat API endpoints as they ship
• Better error handling — structured error responses with actionable hints
• OAuth/OIDC support — for Tracecat instances using SSO instead of basic auth
• Test suite — automated integration tests against a live Tracecat instance

Contributions, issues, and feature requests are welcome.

Related Projects

• tracecat-skills — Claude Code skills for Tracecat workflow building

Note: This project was previously named tracecat-mcp. It has been renamed to tracecat-mcp-community to clearly distinguish it from Tracecat's official MCP server which uses OAuth authentication.

• Tracecat — The open-source SOAR platform
• MCP SDK — Model Context Protocol TypeScript SDK

License

MIT