# plextrac-mcp2

Unofficial MCP server for PlexTrac, backed by
[`plextrac-api2`](https://github.com/erikrubstein/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.

## Installation

Install from GitHub with `pipx`:

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

Confirm the executable is available:

```bash
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](#development).

## Add To Codex

```bash
codex mcp add plextrac -- plextrac-mcp
```

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

```bash
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

```bash
claude mcp add --scope user plextrac -- plextrac-mcp
```

With a custom session path:

```bash
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:

```json
{
  "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:

```bash
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:

```text
~/.config/plextrac/session.json
```

The MCP server intentionally uses the same session and keyring conventions as
[`plextrac-cli2`](https://github.com/erikrubstein/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:

```text
{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:

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

```json
{
  "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

```bash
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:

```bash
.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.