plextrac-mcp2

Unofficial MCP server for PlexTrac, backed by plextrac-api2.

This project is not affiliated with, endorsed by, or supported by PlexTrac.

plextrac-mcp2 gives MCP-capable agents such as Codex, Claude, and MCP Inspector access to PlexTrac over stdio. It follows the same philosophy as monarch-mcp2: expose a broad API surface, but keep default responses compact and readable so agents do not burn context on raw payloads unless they ask for them.

What This Is For

The server is useful when an agent needs to help with PlexTrac work such as:

• finding clients, reports, findings, assets, users, and templates

• creating, editing, copying, or moving findings

• building report content from existing writeups and templates

• attaching or inspecting evidence, artifacts, and affected assets

• working with assessments, content libraries, runbooks, and scheduler data

• performing administrative lookups when the authenticated user has permission

The current server registers 335 tools across the polished PlexTrac API groups exposed by plextrac-api2. The common API helpers are not exposed as a separate MCP group, and webhook receiver helpers are intentionally omitted.

Related MCP server: reptor-mcp

Installation

Install from GitHub with pipx:

pipx install git+https://github.com/erikrubstein/plextrac-mcp2.git

Confirm the executable is available:

which plextrac-mcp

The package depends on plextrac-api2 from GitHub. During local development you can install a sibling checkout of the API in editable mode; see Development.

Add To Codex

codex mcp add plextrac -- plextrac-mcp

If your session file is somewhere other than the default path:

codex mcp add \
  --env PLEXTRAC_SESSION_PATH="/absolute/path/to/session.json" \
  plextrac \
  -- plextrac-mcp

Then restart Codex or open a new Codex thread so the server is loaded.

Add To Claude Code

claude mcp add --scope user plextrac -- plextrac-mcp

With a custom session path:

claude mcp add --scope user \
  -e PLEXTRAC_SESSION_PATH="/absolute/path/to/session.json" \
  plextrac \
  -- plextrac-mcp

Add To Claude Desktop

Add an entry like this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "plextrac": {
      "command": "plextrac-mcp",
      "env": {
        "PLEXTRAC_SESSION_PATH": "/absolute/path/to/session.json"
      }
    }
  }
}

Omit env if you use the default session path.

Use With MCP Inspector

MCP Inspector is a good way to inspect the tool list and try calls directly:

npx @modelcontextprotocol/inspector plextrac-mcp

If plextrac-mcp is not on your PATH, pass the absolute path from which plextrac-mcp.

Sessions And Credentials

The default session file is:

~/.config/plextrac/session.json

The MCP server intentionally uses the same session and keyring conventions as plextrac-cli2:

• PLEXTRAC_CONFIG_DIR changes the config directory.

• PLEXTRAC_SESSION_PATH changes the session file.

• PLEXTRAC_PROFILE changes the keyring credential profile.

• PLEXTRAC_KEYRING_SERVICE changes the keyring service name.

By default the keyring service is plextrac-cli2, so sessions and saved credentials created by the CLI can be reused by the MCP server.

Authentication tools include:

• auth_create_session

• auth_session_from_token

• auth_get_session_status

• auth_refresh_session

• auth_load_session

• auth_save_session

• auth_use_session

• auth_export_session

• auth_logout

• auth_forget_credentials

Auth tools redact tokens by default. Set include_token=true only when a trusted caller explicitly needs the bearer token.

Tool Names

Tool names use:

{group}_{function_name}

Examples:

• clients_list_clients

• reports_list_reports

• reports_get_report

• findings_list_report_findings

• findings_get_finding

• findings_create_finding

• assets_list_report_assets

• affected_assets_bulk_create_affected_asset_status_updates

• files_list_artifacts

• content_library_list_writeup_repositories

• runbooks_list_runbook_repositories

The broad API groups are useful for full coverage, but most day-to-day report writing tends to involve clients, reports, findings, assets, affected assets, files, templates, content library, assessments, and runbooks.

Output Controls

Every registered API tool accepts the same output controls:

• output_mode="summary" returns curated, compact output by default.

• output_mode="full" returns complete structured data without raw API payloads.

• output_mode="raw" returns complete structured data including raw API payloads when available.

• fields=[...] returns only selected dotted paths from the output.

Examples:

{
  "client_id": "client-123",
  "output_mode": "summary"
}

{
  "client_id": "client-123",
  "report_id": "report-456",
  "fields": ["report_id", "name", "status", "findings_count"]
}

Summary output is hand-curated in this repository. If a summary is confusing, too noisy, or missing the values an agent needs for normal work, that is a bug worth fixing here instead of forcing every caller to use raw output.

Helpful Workflows

For report-writing and finding work, these tools are usually the best starting points:

• clients_list_clients and clients_get_client to identify the right client.

• reports_list_reports and reports_get_report to inspect the report target.

• findings_list_report_findings and findings_get_finding to understand existing report content.

• findings_create_finding, findings_update_finding, and related finding tools to draft or revise findings.

• content_library_list_writeup_repositories and related content-library tools to reuse approved writeups.

• templates_list_report_templates to inspect report template options.

• assets_list_report_assets and affected-asset tools to connect findings to impacted systems.

• files_list_artifacts and file tools to locate or attach supporting evidence.

This MCP server is intentionally large. Agents should prefer these high-value tools first, then reach for the more specialized groups when the task calls for them.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .

When testing against a local plextrac-api2 checkout:

.venv/bin/python -m pip install -e ../plextrac-api2
.venv/bin/python -m pip install --no-deps -e ".[dev]"

Useful files:

• src/plextrac_mcp/server.py registers MCP groups.

• src/plextrac_mcp/groups/ contains group-specific tool wrappers.

• src/plextrac_mcp/output.py contains curated summaries.

• src/plextrac_mcp/tool_metadata.py adds output controls and annotations.

• src/plextrac_mcp/session.py and src/plextrac_mcp/credentials.py handle sessions and keyring credentials.

See AGENTS.md for contributor and coding-agent guidance.