@horizonapp/mcp-server

The official Model Context Protocol (MCP) server for Horizon — connect any AI tool to your project management workspace.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Quick Start

1. Create a Personal API Token

Go to Settings > Account > API Tokens in Horizon and create a new token. Copy it — you won't see it again.

2. Add to your AI tool

Add this to your MCP config file:

Claude Code (.mcp.json or ~/.claude/mcp.json):

{
  "mcpServers": {
    "horizon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@horizonapp/mcp-server"],
      "env": {
        "HORIZON_API_TOKEN": "horizon_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "horizon": {
      "command": "npx",
      "args": ["-y", "@horizonapp/mcp-server"],
      "env": {
        "HORIZON_API_TOKEN": "horizon_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Windsurf — add the same config to your Windsurf MCP settings file.

3. Restart your AI tool

Horizon tools will be automatically available. Try asking your AI to "list my workspaces" or "show my tasks".

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HORIZON_API_TOKEN | Yes | Your Personal API Token (horizon_pat_...) | | HORIZON_API_URL | No | API endpoint. Defaults to https://api.horizonapp.dev/graphql |

Available Tools

Read (10 tools)

| Tool | Description | |------|-------------| | list_workspaces | List all workspaces you have access to | | list_teams | List teams in a workspace | | query_tasks | Search and filter tasks by status, assignee, project, keyword | | query_projects | List projects with health, progress, and lead info | | query_cycles | List cycles (sprints) with progress stats | | query_wiki | Search wiki pages by title | | read_wiki_page | Read the full content of a wiki page | | query_feedback | Search feedback items by type, status, and keyword | | query_team | List team members with roles and email | | query_labels | List available labels for a team |

Write (4 tools)

| Tool | Description | |------|-------------| | create_task | Create a new task in a project | | update_task | Update task title, status, priority, assignee, and more | | create_project | Create a new project in a team | | update_wiki_page | Update wiki page content |

How It Works

AI Tool  -->  MCP Server  -->  Horizon GraphQL API
(stdio)      (translates)      (authenticated via PAT)

1. Your AI tool sends a tool call over stdio (e.g., query_tasks)
2. The MCP server translates it into a GraphQL query with your PAT for authentication
3. The Horizon API processes it with full permission checks and returns data
4. The MCP server formats the response and sends it back to your AI tool

Security

• Tokens are never stored in plaintext — only SHA-256 hashes are in the database
• All existing permission checks apply — RBAC, team access, private teams
• A PAT gives the same access as your session, nothing more
• Tokens can be revoked anytime from Account settings
• Tokens support expiration dates

Important: Never commit your PAT to git. Use ~/.claude/mcp.json (global) or ensure .mcp.json is in your .gitignore.

Local Development

To run against a local Horizon API:

HORIZON_API_TOKEN=your_pat HORIZON_API_URL=http://localhost:8080/graphql npx tsx packages/mcp-server/src/index.ts

License

MIT