Runn

This MCP server provides programmatic access to your Runn data through the Model Context Protocol, enabling AI assistants and clients to read and analyze people, projects, clients, time entries, finances, and related resources. It streamlines data retrieval, caching frequently requested endpoints to reduce API calls and provides secure, role-based access for team collaboration.

How to use

Use an MCP client or integration to connect to the server and request data using the available tools. You can operate in two transport modes: local development (stdio) for quick testing and production (HTTP) for team access. The server handles data from Runn via your API key and enforces access control through OAuth or static tokens.

How to install

Prerequisites: You need Node.js 20.0.0 or higher and a valid Runn API key.

1. Clone and build the project.

# Navigate to the project directory
cd runn-mcp

# Install dependencies
npm install

# Build the project
npm run build

Additional sections

Configuration covers two transport methods. In local development, you run the MCP as a stdio process and wire up clients like Claude Desktop, ChatGPT Desktop, or Cline (VS Code) to the built index. In production, you expose the MCP over HTTP so teammates can connect via a shared URL.

Security and deployment notes

Two authentication methods are supported: OAuth 2.0 Client Credentials for team-wide access and static Bearer tokens for individual clients. You can enable one or both methods. Tokens are stored in memory and will be reissued as needed when using OAuth.

For production, consider hosting behind a reputable gateway or load balancer and enforce TLS. A health check endpoint (/health) is available for readiness probes.

Available tools

get_all_people

Fetches all people from Runn (with optional filters)

get_person_by_id

Fetches a specific person by their ID

get_person_by_email

Fetches a specific person by their email address

get_all_projects

Fetches all projects from Runn (with optional filters)

get_project_by_id

Fetches a specific project by its ID

get_project_phases

Fetches all phases for a project

get_project_milestones

Fetches all milestones for a project

get_all_clients

Fetches all clients from Runn (with optional filters)

get_client_by_id

Fetches a specific client by its ID

get_client_projects

Fetches all projects for a specific client

get_all_assignments

Fetches all assignments (who is assigned to what)

get_active_assignments

Fetches only currently active assignments

get_all_actuals

Fetches all logged time with optional filters

get_person_actuals

Fetches logged time for a specific person

get_project_actuals

Fetches logged time for a specific project

get_all_roles

Fetches all job roles defined in Runn

get_role_by_id

Fetches a specific role by its ID

get_all_contracts

Fetches all employment contracts

get_person_contracts

Fetches contracts for a specific person

get_all_holidays

Fetches all public holidays

get_all_time_off

Fetches all time off/leave entries

get_person_time_off

Fetches time off for a specific person

get_all_milestones

Fetches all project milestones

get_project_milestones

Fetches milestones for a specific project

get_project_phases

Fetches all phases for a specific project

get_all_rate_cards

Fetches all billing rate cards

get_all_placeholders

Fetches all placeholder resources

get_all_tags

Fetches all tags/labels

get_account

Fetches account information and settings

clear_cache

Clears the in-memory cache for all Runn API responses

get_weekly_schedule_vs_actuals_report

Generates a composite report comparing scheduled hours vs actual timesheet hours per project for a given week

get_client_profitability_report

Aggregates financial metrics by client across all their projects