# Ithura MCP server

[![npm](https://img.shields.io/npm/v/ithura-mcp)](https://www.npmjs.com/package/ithura-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-com.ithura%2Fmcp-8a4f6d)](https://registry.modelcontextprotocol.io/v0/servers?search=ithura)
[![license](https://img.shields.io/npm/l/ithura-mcp)](./LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server for
**[Ithura](https://ithura.com)**, a quiet project management workspace for
deliberate teams.

Point Claude, Cursor, or any MCP client at your Ithura workspace and let it read
and write real work: tasks, sprints, projects, modules, wiki pages, and intake.

```
"What is left in the current sprint?"
"Create a task for the login timeout bug and put it in this sprint."
"Summarise every task that moved to Done this week."
```

Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ithura)
as `com.ithura/mcp`.

## Install

No install step. Point your MCP client at `npx`:

```bash
npx ithura-mcp
```

### Claude Desktop / Claude Code

Add to your MCP settings (`claude_desktop_config.json`, or `.mcp.json` in a
project for Claude Code):

```json
{
  "mcpServers": {
    "ithura": {
      "command": "npx",
      "args": ["-y", "ithura-mcp"],
      "env": {
        "ITHURA_API_KEY": "your-api-token",
        "ITHURA_WORKSPACE_SLUG": "your-workspace"
      }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` takes the same block.

## Configuration

| Variable | Required | Default | Notes |
|---|---|---|---|
| `ITHURA_API_KEY` | yes | | Workspace API token, from Settings > API tokens |
| `ITHURA_WORKSPACE_SLUG` | yes | | The slug in your workspace URL |
| `ITHURA_API_URL` | no | `https://api.ithura.com` | Point at your own host when self-hosting |

Create the token in Ithura under **Settings > API tokens**. It carries the
permissions of the member who created it, so create it as a user whose access
matches what you want the agent to have.

## Tools

23 tools across the work graph:

| Area | Tools |
|---|---|
| Projects | `list_projects`, `get_project`, `create_project`, `update_project` |
| Tasks | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `delete_issue` |
| Comments | `list_issue_comments`, `add_issue_comment` |
| Sprints | `list_cycles`, `create_cycle`, `add_issues_to_cycle`, `remove_issue_from_cycle` |
| Modules | `list_modules`, `create_module`, `add_issues_to_module`, `delete_module` |
| Metadata | `list_states`, `list_labels`, `create_label` |
| Search | `search_workspace` |

Every tool returns JSON, so the model sees real field values rather than prose.

## Notes

- The API noun for a work item is `issue` in the HTTP API; the product calls
  them **tasks**. The tool names follow the API.
- Writes are real. Consider a token scoped to a member with limited project
  access if you want the agent kept to a corner of the workspace.
- Self-hosting: set `ITHURA_API_URL` to your instance and everything else works
  unchanged.

## Links

- Ithura: <https://ithura.com>
- Documentation: <https://ithura.com/docs>
- API reference: <https://ithura.com/docs/integrations>

## License

MIT