npm package: @horizonapp/mcp-server
Description: MCP server for Horizon — connect any AI tool to your workspace
Latest version: 0.1.2

# @horizonapp/mcp-server

The official [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Horizon](https://horizonapp.dev) — 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`):

```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`):

```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:

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

## License

MIT