mcp-runrun

MCP server for Runrun.it — gives Claude access to tasks, projects, clients, users, boards and more via the Runrun.it REST API v1.0.

Requirements

• Python 3.11+
• Runrun.it App-Key and User-Token (Settings → Integrations → API)

Setup

# 1. Create & activate venv
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # Mac/Linux

# 2. Install
pip install -e .

Credentials

Copy .env.example to .env in the project root and fill in your keys:

RUNRUN_APP_KEY=your_app_key
RUNRUN_USER_TOKEN=your_user_token

.env is gitignored — credentials never leave your machine and never go into Claude's config files.

Configure in Claude

Mac/Linux — register the wrapper script (it loads .env and starts the server):

claude mcp add --scope user runrun -- /path/to/mcp-runrun/run.sh

For the Claude Desktop app, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "runrun": { "command": "/path/to/mcp-runrun/run.sh" }
  }
}

Windows — register run.bat (same idea: loads .env, starts the server). Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "runrun": { "command": "C:\\mcp-runrun\\run.bat" }
  }
}

Security

• Never commit .env — it is gitignored on purpose. Don't paste real keys into README, issues, commits, or pull requests.
• The User-Token acts as your Runrun.it user: anyone with it can read and change tasks on your behalf. Treat it like a password.
• If a token leaks, revoke and regenerate it immediately at Runrun.it → Settings → Integrations → API.
• Each person must use their own User-Token — don't share tokens between teammates (actions are logged as the token's owner).

Available Tools

Performance & filtering notes

Runrun.it task objects are huge (125 fields, ~5.5 KB each). To stay fast and avoid flooding the model's context, list endpoints (list_tasks, list_projects, list_users, list_clients) return a concise summary by default plus pagination metadata (total, has_more, next_page). Pass detail_level: "full" when you genuinely need every field.

Two distinct people are attached to each task:

• Creator → user_id filter ("tasks I created")
• Responsible / assignee → responsible_id filter ("tasks assigned to me")

For "my cards / tasks I created", use list_my_tasks — it resolves the current user automatically and filters in a single fast call.

Extracting card content & building spreadsheets

The core workflow ("filter cards → read each card's content → standardized spreadsheet") is served by two tools:

• get_task_content — reads ONE card and returns a clean flat record: status, board/stage/project/client/type, creator, responsible, all assignees, dates, time (raw seconds + H:MM:SS), tags, custom fields with human labels resolved (e.g. "Área": "Growth"), and the description converted from HTML to plain text (tables → tab-separated cells, lists → bullets, links preserved as text (url)).
• export_tasks — the workhorse. Same filters as list_tasks, then extracts a standardized record for every matching card (descriptions fetched in parallel, paging past the 100-per-request API ceiling up to max_tasks). Pass flatten_custom_fields: true to get one cf: <label> column per custom field plus a deterministic columns list — drop straight into a spreadsheet. Returns pagination metadata (total, capped, capped_by, errors).

Custom fields that share a label across the org are kept distinct (the field id is appended). Rate-limited (429) requests are retried with backoff.

Tools

Tool	Description
list_tasks	List tasks with filters (creator user_id, responsible_id, project, board, status). Summary + pagination
set_task_fields	Write custom field values on a task. Keys accept field ids or labels; option labels are resolved to ids automatically; null clears
list_field_options	List the selectable options (id + label) of a custom field
list_my_tasks	List the authenticated user's own tasks (created or responsible) in one call
get_task_content	Read one card → standardized record (description as text, tags, resolved custom fields)
export_tasks	Filter + extract every matching card into uniform, spreadsheet-ready rows
list_boards / get_board	Discover boards / board IDs for filtering
get_task	Get a task by ID
create_task	Create a new task. Optional board_id/board_stage_id move it to the right board immediately (the API always creates on the default board)
update_task	Update task fields
delete_task	Delete a task
play_task	Start timer on a task
pause_task	Pause timer on a task
close_task	Close/complete a task
reopen_task	Reopen a closed task
list_task_comments	List comments on a task
add_task_comment	Add a comment to a task
list_task_attachments	List attachments on a task
list_projects	List projects
get_project	Get a project by ID
create_project	Create a project
update_project	Update a project
list_clients	List clients
get_client	Get a client by ID
create_client	Create a client
list_users	List organization users
get_user	Get a user by ID
get_current_user	Get the authenticated user
list_activities	List activity history
list_boards	List boards
get_board_stages	Get stages of a board
list_task_types	List task types
list_teams	List teams

Authentication

Get your credentials at Runrun.it → Settings → API:

• App-Key: the application key for your organization
• User-Token: the personal token for the acting user