MCP Servers

ticket-rs provides two MCP (Model Context Protocol) servers for AI assistants:

Server	Purpose	Use Case
ticket-docs	Search tk documentation	Help AI understand tk commands and features
ticket-mcp	Full issue management tools	Let AI agents create, update, and manage issues

`ticket-docs` (Docs MCP)

The docs MCP server gives AI assistants access to search ticket-rs documentation directly.

Setup

Claude Code
Cursor
Windsurf
Manual

Add to project .mcp.json:

claude mcp add --transport http --scope project ticket-docs https://docs.ticket-rs.io/mcp

Add --scope user to make it available across all projects.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ticket-docs": {
      "url": "https://docs.ticket-rs.io/mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ticket-docs": {
      "serverUrl": "https://docs.ticket-rs.io/mcp"
    }
  }
}

Add to your .mcp.json:

{
  "mcpServers": {
    "ticket-docs": {
      "type": "http",
      "url": "https://docs.ticket-rs.io/mcp"
    }
  }
}

Available Tools

Tool	Description
`search_docs`	Search tk documentation for relevant content

Example prompts:

“How do I add a dependency between issues?”
“What does tk triage show?”
“How do I sync with GitHub?”

`ticket-mcp` (Agentic Tools)

The ticket-mcp package provides full issue management capabilities, allowing AI agents to create, update, and manage issues directly.

Installation

Installer Script (Recommended)
uv
pip

Install everything — the tk binary, Python bindings, and MCP server — in one command:

curl -fsSL https://ticket-rs.io/install.sh | sh -s -- --pkgs=all

This installs the tk binary to ~/.local/bin and creates a virtual environment at ~/.ticket/.venv with ticket-mcp and ticket-py.

To install only the MCP server (without the tk binary or Python bindings):

curl -fsSL https://ticket-rs.io/install.sh | sh -s -- --pkgs=mcp

After installation, the MCP server is available at:

~/.ticket/.venv/bin/ticket-mcp

uv tool install ticket-mcp

pip install ticket-mcp

Requires Python 3.10+. ticket-mcp pulls in ticket-py as a hard dependency — the in-process PyO3 bindings — so no separate tk binary install is needed for the MCP server. You only need the tk binary on PATH if you also want to use the CLI directly.

Setup

Claude Code
Cursor
Manual
From Installer Venv

claude mcp add ticket uvx ticket-mcp

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ticket": {
      "command": "uvx",
      "args": ["ticket-mcp"]
    }
  }
}

Add to your .mcp.json:

{
  "mcpServers": {
    "ticket": {
      "command": "uvx",
      "args": ["ticket-mcp"]
    }
  }
}

If you installed via --pkgs=mcp, use the venv path:

{
  "mcpServers": {
    "ticket": {
      "command": "~/.ticket/.venv/bin/ticket-mcp"
    }
  }
}

Available Tools

ticket-mcp exposes exactly three tools. They route every request through ticket_py.dispatch (in-process PyO3), so the full tk CLI surface — every subcommand, every flag — is reachable without a per-command wrapper.

Tool	Purpose
`tk_help(query="")`	Discovery. `tk_help()` for top-level help; `tk_help("triage")` for a subcommand’s flags.
`tk_run(invocation, json=True)`	Run any `tk` command. The string is parsed with `shlex.split` (no shell, no metachar expansion). `json=True` (default) appends `--format json` if missing and parses the result.
`tk_workspace(path=None)`	Get or set the workspace root used by `tk_run` and `tk_help`.

Usage Example

# Workspace is auto-detected from cwd, git root, or .tickets/ directory.
# To override, set TICKET_WORKSPACE env var or call:
# tk_workspace('/path/to/repo')

# 1. Get AI recommendations
tk_run('triage')   # Full recommendations with health score
tk_run('next')     # Single top pick for quick decisions

# 2. See what's ready to work on
tk_run('ready')

# 3. Start work on an issue
tk_run('claim tk-123')

# 4. Resolve when done (shows newly unblocked issues)
tk_run('resolve tk-123')

# 5. Anything else — every tk subcommand works
tk_run("create 'Fix a bug with spaces' --priority 1")
tk_run('dep add tk-124 tk-123')
tk_run('priority --limit 5')

Why three tools

The previous version exposed 22 hand-written wrappers (ready, create, triage, …), which burned ~3,300 tokens of agent context for tool schemas that drifted whenever the CLI grew a flag. The three-tool surface keeps the agent on a stable contract and delegates schema maintenance to clap’s introspection — every flag added to tk is automatically reachable via tk_run with zero MCP changes.

Which Should I Use?

Docs MCP

Best for learningUse when you want AI to understand tk commands and answer questions about features.

ticket-mcp

Best for automationUse when you want AI agents to actually manage your issues—create, update, close, etc.

Recommendation: Use both together. The docs server helps AI understand how to use tk, while ticket-mcp lets it take action.

Troubleshooting

MCP server not found

Verify the server is configured:

# For Claude Code
claude mcp list

You should see ticket-docs and/or ticket-mcp in the list.

ticket-mcp: ticket-py import error

The MCP server depends on ticket-py (the PyO3 in-process bindings). Reinstall with the package extras present:

uv tool install --upgrade ticket-mcp
# or
pip install --upgrade ticket-mcp

Verify the import works:

python -c "import ticket_py; print(ticket_py.dispatch(['--version']).strip())"

If you previously had a tk binary in PATH and the MCP was routing through subprocess, that path no longer exists — the new server runs tk in-process via the PyO3 bindings only.

ticket-mcp: No issues found

Make sure you’ve set the workspace context and initialized tickets:

# In your project directory
tk init
tk demo  # Create sample issues to test

Connection errors (docs MCP)

The docs MCP server requires internet access to reach docs.ticket-rs.io. Check your network connection.

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

`ticket-docs` (Docs MCP)

Setup

Available Tools

`ticket-mcp` (Agentic Tools)

Installation

Setup

Available Tools

Usage Example

Why three tools

Which Should I Use?

Docs MCP

ticket-mcp

Troubleshooting

Next Steps

Claude Code Setup

CLI Commands

​ticket-docs (Docs MCP)

​Setup

​Available Tools

​ticket-mcp (Agentic Tools)

​Installation

​Setup

​Available Tools

​Usage Example

​Why three tools

​Which Should I Use?

Docs MCP

ticket-mcp

​Troubleshooting

​Next Steps

Claude Code Setup

CLI Commands

`ticket-docs` (Docs MCP)

Setup

Available Tools

`ticket-mcp` (Agentic Tools)

Installation

Setup

Available Tools

Usage Example

Why three tools

Which Should I Use?

Troubleshooting

Next Steps