How do I install Trac?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Trac need an API key?

No required environment variable is listed on this record.

When was Trac last checked?

Last checked 2026-10-28. A MCP (Model Context Protocol) server that provides AI assistants with tools to interact with Trac project management instances — managing tickets, wiki pages, and milestones

Trac MCP server

trac-mcp-server

Standalone MCP server that gives AI agents full access to Trac project management -- tickets, wiki, milestones, and search -- via the Model Context Protocol.

Quick Start

Requires Python 3.10 or later.

pip install .

Set your Trac connection:

export TRAC_URL="https://trac.example.com"
export TRAC_USERNAME="your-username"
export TRAC_PASSWORD="your-password"

Run the server:

trac-mcp-server

Using auto-pm? When trac-mcp-server is driven through auto-pm, auto-pm reads its connection settings from .auto_pm/config.yml in your project root (rather than the environment variables above). Run auto-pm setup in your project directory to generate the file; the resulting .auto_pm/config.yml carries trac.url, trac.username, a ${TRAC_PASSWORD} reference, and component mappings.

Configuration

Configuration via environment variables, .env file, or YAML config file (.trac_mcp/config.yaml):

Variable	Required	Default	Description
`TRAC_URL`	Yes	--	Trac instance URL
`TRAC_USERNAME`	Yes	--	Trac username
`TRAC_PASSWORD`	Yes	--	Trac password
`TRAC_INSECURE`	No	`false`	Skip SSL verification (development only)
`TRAC_DEBUG`	No	`false`	Enable debug logging
`TRAC_MAX_PARALLEL_REQUESTS`	No	`5`	Max parallel XML-RPC requests
`TRAC_MAX_BATCH_SIZE`	No	`500`	Max items per batch operation (1-10000)
`TRAC_RPC_TIMEOUT`	No	`60`	Read timeout in seconds for XML-RPC requests (5-300)
`TRAC_ALLOWED_INSTANCES`	No	--	Comma-separated instances (`/path` on the `TRAC_URL` host, or absolute URL) the default identity may reach; unset = unrestricted. `TRAC_URL` must be on the list (ticket #110)
`TRAC_MCP_TRANSPORT`	No	`stdio`	MCP transport: `stdio` or `http`
`TRAC_MCP_HOST`	No	`127.0.0.1`	Bind host for the `http` transport
`TRAC_MCP_PORT`	No	`8080`	Bind port for the `http` transport
`TRAC_MCP_AUTH_TOKEN`	No	--	Bearer token required by the `http` transport
`TRAC_IDENTITIES`	No	--	Path to a file mapping per-caller bearer tokens to their own Trac username/password (`http` transport only)

For YAML config file format and advanced options, see Configuration Reference. For the http transport specifically, including multi-identity auth, see HTTP Transport.

MCP Client Integration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trac": {
      "command": "trac-mcp-server",
      "env": {
        "TRAC_URL": "https://trac.example.com",
        "TRAC_USERNAME": "your-username",
        "TRAC_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add trac -e TRAC_URL=https://trac.example.com \
  -e TRAC_USERNAME=your-username \
  -e TRAC_PASSWORD=your-password \
  -- trac-mcp-server

Other MCP Clients

Any MCP client that supports stdio transport can launch trac-mcp-server as a subprocess. Pass Trac credentials via environment variables.

For a shared or remote deployment, trac-mcp-server can also serve MCP over streamable HTTP instead of stdio:

TRAC_MCP_AUTH_TOKEN=your-token trac-mcp-server --transport http --port 8080

See HTTP Transport for auth, bind-safety rules, and reverse-proxy guidance.

Format Conversion CLI

The package also installs trac-convert, a standalone CLI for converting between TracWiki and Markdown without requiring a Trac connection. Useful for one-off conversions, editor pipelines, and clipboard workflows.

# Convert Markdown to TracWiki (stdin → stdout)
trac-convert --from md --to tracwiki < README.md > README.tw

# Convert a file (auto-detects source format)
trac-convert --to md notes.tw -o notes.md

# Clipboard round-trip
trac-convert --from-clipboard --to tracwiki --to-clipboard

Supports stdin/stdout pipes, file I/O, and system clipboard on Linux, macOS, and Windows (via pyperclip). See CLI Reference for the full flag list.

Trac Wiki I/O

trac-convert can also read from and write to a live Trac instance via --from-wiki PAGE and --to-wiki PAGE, reusing the same credentials and config precedence as trac-mcp-server: .trac_mcp/config.yml, TRAC_* env vars, or --trac-* CLI flags — CLI wins.

# Verify Trac connectivity (prints resolved config, pings server)
trac-convert --check-trac

# Fetch a Trac wiki page, convert to Markdown, save locally
trac-convert --from-wiki DesignDoc --to md -o design.md

# Edit design.md in your favourite editor, then push it back
trac-convert --from-file design.md --to-wiki DesignDoc --wiki-comment "Refined via CLI"

# One-liner Trac → clipboard for quick reference lookup
trac-convert --from-wiki ReleaseNotes --to md --to-clipboard

Auth setup: use an existing .trac_mcp/config.yml (the same file trac-mcp-server uses) or supply ad-hoc flags — --trac-url, --trac-username, --trac-password-file ~/.trac_pass (prefer --trac-password-file to keep secrets out of shell history). See Configuration for the full precedence rules.

Trac errors (auth, network, page-not-found, permission-denied) exit with code 4 and write a human-readable message to stderr. See CLI Reference for the full flag list.

File Transfer CLI

When the server runs on another machine (the HTTP transport), its file tools cannot see your files, and over HTTP they refuse server-side paths by default. trac-mcp runs on your machine and moves the bytes through the server for you, keeping your identity and the server's conversion and link checks:

trac-mcp wiki-push Docs/Design design.md          # Markdown is converted on the way in
trac-mcp wiki-pull Docs/Design design.md
trac-mcp attach-put --ticket 42 trace.bin
trac-mcp attach-get --page Docs/Design diagram.png diagram.png

It connects with the nearest .mcp.json entry (or --url). See CLI Reference and File Access.

Available Tools (44)

Every tool below also accepts an optional instance argument to route the call to another Trac project on the same host (or a named instance from config) instead of the default -- see Multiple Instances.

Tickets (11)

Tool	Description
`ticket_search`	Search tickets with Trac query language
`ticket_get`	Get ticket details by ID
`ticket_create`	Create new tickets
`ticket_update`	Update existing tickets
`ticket_delete`	Delete tickets
`ticket_changelog`	Get ticket change history
`ticket_fields`	List available ticket fields
`ticket_actions`	Get available ticket actions
`ticket_batch_create`	Create multiple tickets in one batch
`ticket_batch_delete`	Delete multiple tickets in one batch
`ticket_batch_update`	Update multiple tickets in one batch

Ticket Attachments (4)

Tool	Description
`ticket_attachment_put`	Upload a local file as an attachment to a ticket (bytes sent via XML-RPC, not inlined)
`ticket_attachment_get`	Download a ticket attachment to a local file (bytes written to output_path, not inlined)
`ticket_attachment_list`	List attachments on a ticket
`ticket_attachment_delete`	Delete a ticket attachment (requires TICKET_ADMIN)

Ticket Admin (6)

Tool	Description
`ticket_component_create`	Create a new ticket component (requires TICKET_ADMIN)
`ticket_component_list`	List all ticket components
`ticket_component_delete`	Delete a ticket component (requires TICKET_ADMIN)
`ticket_enum_create`	Create a new enum value (priority, resolution, severity, type, version) — requires TICKET_ADMIN
`ticket_enum_list`	List enum values for a given enum type
`ticket_enum_delete`	Delete an enum value (requires TICKET_ADMIN)

Wiki (8)

Tool	Description
`wiki_get`	Get wiki page content as stored (TracWiki, byte-for-byte)
`wiki_search`	Search wiki pages
`wiki_create`	Create new wiki pages (content stored byte-for-byte)
`wiki_update`	Update existing wiki pages (content stored byte-for-byte)
`wiki_delete`	Delete wiki pages
`wiki_recent_changes`	List recent wiki changes
`wiki_get_history`	Get version history for a wiki page
`wiki_diff`	Unified diff between two versions of a wiki page, with the change comments in between

Wiki Files (3)

Tool	Description
`wiki_file_push`	Push local file to wiki (auto format conversion)
`wiki_file_pull`	Pull wiki page to local file
`wiki_file_detect_format`	Detect content format (Markdown/TracWiki)

Wiki Attachments (4)

Tool	Description
`wiki_attachment_put`	Upload a local file as an attachment to a wiki page (bytes sent via XML-RPC, not inlined)
`wiki_attachment_get`	Download a wiki attachment to a local file (bytes written to output_path, not inlined)
`wiki_attachment_list`	List attachments on a wiki page
`wiki_attachment_delete`	Delete a wiki attachment (requires WIKI_DELETE)

Milestones (5)

Tool	Description
`milestone_list`	List all milestones
`milestone_get`	Get milestone details
`milestone_create`	Create new milestones
`milestone_update`	Update existing milestones
`milestone_delete`	Delete milestones

System (2)

Tool	Description
`ping`	Test connectivity and return API version
`get_server_time`	Get Trac server time

Instances (1)

Tool	Description
`list_instances`	List configured and (via discovery) host-visible Trac instances

Development

pip install -e ".[dev]"
pytest tests/ -v

The two CI halves

./ci.sh        # lint + offline tests + dual-binary build. Hermetic:
               # no credentials, no daemon, no network
./ci-live.sh   # the same suite with --run-live, against a real Trac

ci.sh is what GitHub Actions runs, and it deliberately does not pass --run-live, so every @pytest.mark.live test is skipped there. Those tests are the only place this project exercises the real Trac substrate, so run ci-live.sh too before deploying a change to a shared daemon. It needs TRAC_URL, TRAC_USERNAME and TRAC_PASSWORD (see .env.example), and without them it exits non-zero without running pytest — not run must not be able to look like passed.

ci.sh runs the offline suite with TRAC_* scrubbed from the environment, and .env is loaded only under --run-live. An offline test that needs credentials therefore fails locally rather than only on Actions.

Project Structure

src/trac_mcp_server/
  config.py       # Environment variable configuration
  core/           # Trac XML-RPC client, async utilities
  mcp/            # MCP server, tools, resources
  converters/     # Markdown <-> TracWiki conversion
  detection/      # Content format detection

Documentation

See docs/reference/overview.md for detailed tool reference, configuration, and troubleshooting.

trac-mcp-server

Standalone MCP server that gives AI agents full access to Trac project management -- tickets, wiki, milestones, and search -- via the Model Context Protocol.

Quick Start

Requires Python 3.10 or later.

pip install .

Set your Trac connection:

export TRAC_URL="https://trac.example.com"
export TRAC_USERNAME="your-username"
export TRAC_PASSWORD="your-password"

Run the server:

trac-mcp-server

Using auto-pm? When trac-mcp-server is driven through auto-pm, auto-pm reads its connection settings from .auto_pm/config.yml in your project root (rather than the environment variables above). Run auto-pm setup in your project directory to generate the file; the resulting .auto_pm/config.yml carries trac.url, trac.username, a ${TRAC_PASSWORD} reference, and component mappings.

Configuration

Configuration via environment variables, .env file, or YAML config file (.trac_mcp/config.yaml):

Variable	Required	Default	Description
`TRAC_URL`	Yes	--	Trac instance URL
`TRAC_USERNAME`	Yes	--	Trac username
`TRAC_PASSWORD`	Yes	--	Trac password
`TRAC_INSECURE`	No	`false`	Skip SSL verification (development only)
`TRAC_DEBUG`	No	`false`	Enable debug logging
`TRAC_MAX_PARALLEL_REQUESTS`	No	`5`	Max parallel XML-RPC requests
`TRAC_MAX_BATCH_SIZE`	No	`500`	Max items per batch operation (1-10000)
`TRAC_RPC_TIMEOUT`	No	`60`	Read timeout in seconds for XML-RPC requests (5-300)
`TRAC_ALLOWED_INSTANCES`	No	--	Comma-separated instances (`/path` on the `TRAC_URL` host, or absolute URL) the default identity may reach; unset = unrestricted. `TRAC_URL` must be on the list (ticket #110)
`TRAC_MCP_TRANSPORT`	No	`stdio`	MCP transport: `stdio` or `http`
`TRAC_MCP_HOST`	No	`127.0.0.1`	Bind host for the `http` transport
`TRAC_MCP_PORT`	No	`8080`	Bind port for the `http` transport
`TRAC_MCP_AUTH_TOKEN`	No	--	Bearer token required by the `http` transport
`TRAC_IDENTITIES`	No	--	Path to a file mapping per-caller bearer tokens to their own Trac username/password (`http` transport only)

For YAML config file format and advanced options, see Configuration Reference. For the http transport specifically, including multi-identity auth, see HTTP Transport.

MCP Client Integration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trac": {
      "command": "trac-mcp-server",
      "env": {
        "TRAC_URL": "https://trac.example.com",
        "TRAC_USERNAME": "your-username",
        "TRAC_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add trac -e TRAC_URL=https://trac.example.com \
  -e TRAC_USERNAME=your-username \
  -e TRAC_PASSWORD=your-password \
  -- trac-mcp-server

Other MCP Clients

Any MCP client that supports stdio transport can launch trac-mcp-server as a subprocess. Pass Trac credentials via environment variables.

For a shared or remote deployment, trac-mcp-server can also serve MCP over streamable HTTP instead of stdio:

TRAC_MCP_AUTH_TOKEN=your-token trac-mcp-server --transport http --port 8080

See HTTP Transport for auth, bind-safety rules, and reverse-proxy guidance.

Format Conversion CLI

# Convert Markdown to TracWiki (stdin → stdout)
trac-convert --from md --to tracwiki < README.md > README.tw

# Convert a file (auto-detects source format)
trac-convert --to md notes.tw -o notes.md

# Clipboard round-trip
trac-convert --from-clipboard --to tracwiki --to-clipboard

Supports stdin/stdout pipes, file I/O, and system clipboard on Linux, macOS, and Windows (via pyperclip). See CLI Reference for the full flag list.

Trac Wiki I/O

# Verify Trac connectivity (prints resolved config, pings server)
trac-convert --check-trac

# Fetch a Trac wiki page, convert to Markdown, save locally
trac-convert --from-wiki DesignDoc --to md -o design.md

# Edit design.md in your favourite editor, then push it back
trac-convert --from-file design.md --to-wiki DesignDoc --wiki-comment "Refined via CLI"

# One-liner Trac → clipboard for quick reference lookup
trac-convert --from-wiki ReleaseNotes --to md --to-clipboard

Trac errors (auth, network, page-not-found, permission-denied) exit with code 4 and write a human-readable message to stderr. See CLI Reference for the full flag list.

File Transfer CLI

trac-mcp wiki-push Docs/Design design.md          # Markdown is converted on the way in
trac-mcp wiki-pull Docs/Design design.md
trac-mcp attach-put --ticket 42 trace.bin
trac-mcp attach-get --page Docs/Design diagram.png diagram.png

It connects with the nearest .mcp.json entry (or --url). See CLI Reference and File Access.

Available Tools (44)

Tickets (11)

Tool	Description
`ticket_search`	Search tickets with Trac query language
`ticket_get`	Get ticket details by ID
`ticket_create`	Create new tickets
`ticket_update`	Update existing tickets
`ticket_delete`	Delete tickets
`ticket_changelog`	Get ticket change history
`ticket_fields`	List available ticket fields
`ticket_actions`	Get available ticket actions
`ticket_batch_create`	Create multiple tickets in one batch
`ticket_batch_delete`	Delete multiple tickets in one batch
`ticket_batch_update`	Update multiple tickets in one batch

Ticket Attachments (4)

Tool	Description
`ticket_attachment_put`	Upload a local file as an attachment to a ticket (bytes sent via XML-RPC, not inlined)
`ticket_attachment_get`	Download a ticket attachment to a local file (bytes written to output_path, not inlined)
`ticket_attachment_list`	List attachments on a ticket
`ticket_attachment_delete`	Delete a ticket attachment (requires TICKET_ADMIN)

Ticket Admin (6)

Tool	Description
`ticket_component_create`	Create a new ticket component (requires TICKET_ADMIN)
`ticket_component_list`	List all ticket components
`ticket_component_delete`	Delete a ticket component (requires TICKET_ADMIN)
`ticket_enum_create`	Create a new enum value (priority, resolution, severity, type, version) — requires TICKET_ADMIN
`ticket_enum_list`	List enum values for a given enum type
`ticket_enum_delete`	Delete an enum value (requires TICKET_ADMIN)

Wiki (8)

Tool	Description
`wiki_get`	Get wiki page content as stored (TracWiki, byte-for-byte)
`wiki_search`	Search wiki pages
`wiki_create`	Create new wiki pages (content stored byte-for-byte)
`wiki_update`	Update existing wiki pages (content stored byte-for-byte)
`wiki_delete`	Delete wiki pages
`wiki_recent_changes`	List recent wiki changes
`wiki_get_history`	Get version history for a wiki page
`wiki_diff`	Unified diff between two versions of a wiki page, with the change comments in between

Wiki Files (3)

Tool	Description
`wiki_file_push`	Push local file to wiki (auto format conversion)
`wiki_file_pull`	Pull wiki page to local file
`wiki_file_detect_format`	Detect content format (Markdown/TracWiki)

Wiki Attachments (4)

Tool	Description
`wiki_attachment_put`	Upload a local file as an attachment to a wiki page (bytes sent via XML-RPC, not inlined)
`wiki_attachment_get`	Download a wiki attachment to a local file (bytes written to output_path, not inlined)
`wiki_attachment_list`	List attachments on a wiki page
`wiki_attachment_delete`	Delete a wiki attachment (requires WIKI_DELETE)

Milestones (5)

Tool	Description
`milestone_list`	List all milestones
`milestone_get`	Get milestone details
`milestone_create`	Create new milestones
`milestone_update`	Update existing milestones
`milestone_delete`	Delete milestones

System (2)

Tool	Description
`ping`	Test connectivity and return API version
`get_server_time`	Get Trac server time

Instances (1)

Tool	Description
`list_instances`	List configured and (via discovery) host-visible Trac instances

Development

pip install -e ".[dev]"
pytest tests/ -v

The two CI halves

./ci.sh        # lint + offline tests + dual-binary build. Hermetic:
               # no credentials, no daemon, no network
./ci-live.sh   # the same suite with --run-live, against a real Trac

Project Structure

src/trac_mcp_server/
  config.py       # Environment variable configuration
  core/           # Trac XML-RPC client, async utilities
  mcp/            # MCP server, tools, resources
  converters/     # Markdown <-> TracWiki conversion
  detection/      # Content format detection

Documentation

See docs/reference/overview.md for detailed tool reference, configuration, and troubleshooting.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Trac?

Does Trac need an API key?

What transport does Trac use?

When was Trac last checked?

Documentation

trac-mcp-server

Quick Start

Configuration

MCP Client Integration

Claude Desktop

Claude Code

Other MCP Clients

Format Conversion CLI

Trac Wiki I/O

File Transfer CLI

Available Tools (44)

Tickets (11)

Ticket Attachments (4)

Ticket Admin (6)

Wiki (8)

Wiki Files (3)

Wiki Attachments (4)

Milestones (5)

System (2)

Instances (1)

Development

The two CI halves

Project Structure

Documentation

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Trac?

Does Trac need an API key?

What transport does Trac use?

When was Trac last checked?

Documentation

trac-mcp-server

Quick Start

Configuration

MCP Client Integration

Claude Desktop

Claude Code

Other MCP Clients

Format Conversion CLI

Trac Wiki I/O

File Transfer CLI

Available Tools (44)

Tickets (11)

Ticket Attachments (4)

Ticket Admin (6)

Wiki (8)

Wiki Files (3)

Wiki Attachments (4)

Milestones (5)

System (2)

Instances (1)

Development

The two CI halves

Project Structure

Documentation