Skip to main content
Glama

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.

Related MCP server: OpenProject MCP Server

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, unless TRAC_MCP_OIDC_RPC_URL is set

--

Trac username

TRAC_PASSWORD

Yes, unless TRAC_MCP_OIDC_RPC_URL is set

--

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_MCP_OIDC_RPC_URL

No

--

OIDC-protected XML-RPC URL for per-user auth (shared/multi-tenant http deployments) -- see HTTP Transport: OIDC Per-User Auth

TRAC_MCP_OIDC_ALLOW_INSECURE_HTTP

No

false

Accept a plain http TRAC_MCP_OIDC_RPC_URL on a non-loopback host, which sends users' access tokens unencrypted. Refused at startup otherwise

TRAC_MCP_DISABLED_TOOLS

No

(empty)

Comma-separated tool names to leave out, e.g. tools needing a Trac plugin the server lacks -- see Tool Architecture: Disabling Individual Tools

TRAC_MCP_READ_ONLY

No

false

Expose only read-only tools, regardless of transport -- see Tool Architecture: Read-Only Filtering

TRAC_MCP_ALLOWED_HOSTS

No

--

Comma-separated Host headers the http transport accepts besides loopback and the bind address, e.g. trac-mcp:8080 for a docker-compose service name; replaces YAML allowed_hosts

TRAC_MCP_ALLOWED_ORIGINS

No

--

Comma-separated Origin headers the http transport accepts, with scheme, e.g. http://trac-mcp:8080; replaces YAML allowed_origins

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. Markdown -> TracWiki runs offline. TracWiki -> Markdown needs a Trac connection: Trac renders the text and trac-convert translates its HTML, so with no Trac configured it exits 4 and says what to set. 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 TracWiki file to Markdown (Trac renders it; needs a Trac connection)
trac-convert --from tracwiki --to md notes.tw -o notes.md

# Clipboard in, clipboard out
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, or TracWiki -> Markdown with no Trac to render it) exit with code 4 and write a human-readable message to stderr; with --to-wiki, exit 4 means nothing was stored. If --to-wiki stored the page but reading back its new version failed, it exits 5 -- do not retry the write. 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 wiki-pull Docs/Design design.md --assets static/images --assets-url /images   # also saves the page's attachments, relinked
trac-mcp attach-put --ticket 42 trace.bin
trac-mcp attach-get --page Docs/Design diagram.png diagram.png
trac-mcp ticket-comment 42 note.wiki              # TracWiki body sent verbatim; prints the new comment number
trac-mcp ticket-comment-edit 42 3 note.wiki       # replace comment 3 from a file, verified byte for byte; --expect-file OLD guards a web edit
trac-mcp ticket-describe 42 body.wiki             # replace the description, locked against concurrent edits
trac-mcp ticket-create --summary "Title" --description-file body.wiki
trac-mcp ticket-pull 42 body.wiki [--comment N]   # description (or one comment) back, byte for byte

It connects with the nearest .mcp.json entry (or --url). Exit 1 means the server refused and nothing was stored; exit 4 means the write WAS stored but reading it back failed (a ticket-comment's number, a ticket-comment-edit's stored text, or a wiki-push's new page version), so do not retry it. See CLI Reference and File Access.

Available Tools (54)

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 -- except over HTTP with OIDC per-user auth (TRAC_MCP_OIDC_RPC_URL), where calls go only to the configured endpoint and the argument is not offered.

Tickets (12)

Tool

Description

ticket_search

Search tickets with Trac query language

ticket_check_list

Check a whole list of ticket numbers or texts against Trac in one call

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 Comments (4)

These four need the tracrpc_comment Trac plugin on the server (see plugins/README.md); without it each call returns a method_not_available error that says to install the plugin.

Tool

Description

ticket_comment_reply

Post a threaded reply to a ticket comment, optionally quoting the parent

ticket_comment_edit

Correct the text of an existing ticket comment (the old text is kept as a revision; needs base_ts)

ticket_comment_delete

Delete a ticket comment permanently (refuses one posted with field changes unless forced; requires TICKET_ADMIN)

ticket_comment_history

Read the edit revisions of a ticket comment, oldest first

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 (9)

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_conventions

An instance's declared wiki style, the style page's body, and its PageTemplates/* pages, in one call

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 (Markdown is Trac's rendered HTML, translated: a one-way export)

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)

Previews and Render Checks (3)

Tool

Description

convert_preview

Dry-run Markdown or TracWiki through the converter and Trac's renderer, with no write: stored text, HTML and warnings

ticket_render_check

Fetch a ticket's live rendered page and return link facts and warnings

wiki_render_check

Fetch a wiki page's live rendered HTML and return link facts and warnings

Milestones (5)

Tool

Description

milestone_list

List milestones, optionally by name prefix, open or completed, with due and completion dates

milestone_get

Get milestone details

milestone_create

Create new milestones

milestone_update

Update existing milestones

milestone_delete

Delete milestones

Timeline (1)

timeline_search needs the same tracrpc_comment plugin (see plugins/README.md); without it the call returns a method_not_available error that says to install the plugin.

Tool

Description

timeline_search

Search the Trac timeline (tickets, wiki edits, changesets, milestones), author-attributed, as plain text

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.

The live rows write only to the /trac_test instance: by default the one on TRAC_URL's host and port. If that instance has its own origin, set TRAC_TEST_URL (for example http://trac.example.org:8001/trac_test; the path must end with /trac_test) and every live row follows it.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with ClickUp tasks, spaces, lists, and folders through the Model Context Protocol, supporting task creation, updates, moves, duplicates, and workspace organization.
      1,086 npm
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to manage Trilium Notes with full CRUD operations, search, calendar integration, and system administration through the Model Context Protocol.
      23 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents to interact with Redmine projects, issues, time tracking, and members through natural language via the Model Context Protocol.
      -