> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Model Context Protocol servers for AI assistants

ticket-rs provides two MCP ([Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)) 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

<Tabs>
  <Tab title="Claude Code">
    Add to project [`.mcp.json`](https://code.claude.com/docs/en/mcp#project-scope):

    ```bash theme={null}
    claude mcp add --transport http --scope project ticket-docs https://docs.ticket-rs.io/mcp
    ```

    <Tip>
      Add `--scope user` to make it available across all projects.
    </Tip>
  </Tab>

  <Tab title="Cursor">
    Add to [`~/.cursor/mcp.json`](https://cursor.com/docs/context/mcp#using-mcpjson):

    ```json theme={null}
    {
      "mcpServers": {
        "ticket-docs": {
          "url": "https://docs.ticket-rs.io/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to [`~/.codeium/windsurf/mcp_config.json`](https://docs.windsurf.com/windsurf/cascade/mcp#mcp_config-json):

    ```json theme={null}
    {
      "mcpServers": {
        "ticket-docs": {
          "serverUrl": "https://docs.ticket-rs.io/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Manual">
    Add to your `.mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ticket-docs": {
          "type": "http",
          "url": "https://docs.ticket-rs.io/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="Installer Script (Recommended)">
    Install everything — the `tk` binary, Python bindings, and MCP server — in one command:

    ```bash theme={null}
    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.

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

      ```bash theme={null}
      curl -fsSL https://ticket-rs.io/install.sh | sh -s -- --pkgs=mcp
      ```
    </Tip>

    After installation, the MCP server is available at:

    ```bash theme={null}
    ~/.ticket/.venv/bin/ticket-mcp
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv tool install ticket-mcp
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install ticket-mcp
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

### Setup

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add ticket uvx ticket-mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ticket": {
          "command": "uvx",
          "args": ["ticket-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Manual">
    Add to your `.mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ticket": {
          "command": "uvx",
          "args": ["ticket-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="From Installer Venv">
    If you installed via `--pkgs=mcp`, use the venv path:

    ```json theme={null}
    {
      "mcpServers": {
        "ticket": {
          "command": "~/.ticket/.venv/bin/ticket-mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 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

```python theme={null}
# 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?

<CardGroup cols={2}>
  <Card title="Docs MCP" icon="book">
    **Best for learning**

    Use when you want AI to understand tk commands and answer questions about features.
  </Card>

  <Card title="ticket-mcp" icon="robot">
    **Best for automation**

    Use when you want AI agents to actually manage your issues—create, update, close, etc.
  </Card>
</CardGroup>

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

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not found">
    Verify the server is configured:

    ```bash theme={null}
    # For Claude Code
    claude mcp list
    ```

    You should see `ticket-docs` and/or `ticket-mcp` in the list.
  </Accordion>

  <Accordion title="ticket-mcp: ticket-py import error">
    The MCP server depends on `ticket-py` (the PyO3 in-process bindings).
    Reinstall with the package extras present:

    ```bash theme={null}
    uv tool install --upgrade ticket-mcp
    # or
    pip install --upgrade ticket-mcp
    ```

    Verify the import works:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="ticket-mcp: No issues found">
    Make sure you've set the workspace context and initialized tickets:

    ```bash theme={null}
    # In your project directory
    tk init
    tk demo  # Create sample issues to test
    ```
  </Accordion>

  <Accordion title="Connection errors (docs MCP)">
    The docs MCP server requires internet access to reach `docs.ticket-rs.io`. Check your network connection.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Claude Code Setup" icon="wand-magic-sparkles" href="/integrations/claude-code">
    Full Claude Code integration with tk prime hooks.
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/cli-reference/commands">
    Complete command reference.
  </Card>
</CardGroup>