npm package: @focus-pocus/mcp-server
Description: Model Context Protocol (MCP) server for Focus Pocus — manage tasks, track work, and monitor goals from Claude Code or any MCP-compatible client
Author: Focus Pocus
Latest version: 0.5.0

# @focus-pocus/mcp-server

[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Focus Pocus](https://focuspocusapp.com) — manage tasks, track work, and monitor goals from any MCP client.

## Quick Start

### 1. Get a Personal Access Token

In Focus Pocus, go to **Settings > API Access** and create a token. Copy it — it's only shown once.

### 2. Configure your MCP client

**Claude Code (CLI)**

```bash
claude mcp add focus-pocus \
  --transport stdio \
  -e FOCUS_POCUS_API_URL=https://api.focuspocusapp.com \
  -e FOCUS_POCUS_TOKEN=fp_pat_your_token_here \
  -- npx -y @focus-pocus/mcp-server
```

**Claude Desktop / JSON config**

Add to your MCP settings file (e.g. `~/.claude/mcp.json` or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "focus-pocus": {
      "command": "npx",
      "args": ["-y", "@focus-pocus/mcp-server"],
      "env": {
        "FOCUS_POCUS_API_URL": "https://api.focuspocusapp.com",
        "FOCUS_POCUS_TOKEN": "fp_pat_your_token_here"
      }
    }
  }
}
```

**Self-hosted instance** — replace the API URL with your own (e.g. `http://localhost:3001`).

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FOCUS_POCUS_TOKEN` | Yes | Personal Access Token from Settings > API Access |
| `FOCUS_POCUS_API_URL` | Yes | Focus Pocus API URL (`https://api.focuspocusapp.com` or self-hosted) |

## Available Tools (27)

### Tasks

| Tool | Description |
|------|-------------|
| `get_active_tasks` | Get only actionable tasks — excludes habits, expired items, and drafts. Best default. |
| `list_tasks` | List tasks with full filter control (completion, status, priority, difficulty, habits, expired, blocked, pagination) |
| `create_task` | Create a task with name, priority, difficulty, due date, and goal |
| `update_task` | Update specific fields on an existing task |
| `complete_task` | Mark a task as completed |
| `block_task` | Mark a task as blocked |
| `unblock_task` | Mark a task as unblocked |
| `get_task` | Get full task details by ID |
| `search_tasks` | Semantic text search across tasks |

### Work Tracking

| Tool | Description |
|------|-------------|
| `start_working` | Start a work session on a task |
| `stop_working` | Stop tracking work on a task |
| `get_current_work` | List tasks currently being worked on |
| `get_work_summary` | Activity summary with recent work sessions |
| `stop_all_work` | Stop all active work sessions at once |

### Goals

| Tool | Description |
|------|-------------|
| `get_active_goals` | Get only active (non-archived) goals. Best default. |
| `list_goals` | List all goals with optional `isArchived` filter |
| `get_goal` | Get goal details including tasks and milestones |
| `create_goal` | Create a new goal with name, description, and color |
| `link_task_to_goal` | Associate a task with a goal |

### Eisenhower Matrix

| Tool | Description |
|------|-------------|
| `get_eisenhower_quadrant` | Get tasks for a specific Eisenhower matrix quadrant (do-first, schedule, delegate, eliminate, backlog) |

### Insights

| Tool | Description |
|------|-------------|
| `get_insights` | Productivity stats — overdue items, completed today, goal alignment |
| `get_follow_up_items` | Surface stale, abandoned, or overdue tasks |
| `find_related_tasks` | Find semantically related tasks by concept |

### Collaboration

| Tool | Description |
|------|-------------|
| `list_collaborators` | List people you collaborate with across shared goals |
| `get_goal_collaborators` | List collaborators on a specific goal |
| `list_tasks_for_collaborator` | List tasks for a specific collaborator |

### Comments

| Tool | Description |
|------|-------------|
| `add_comment` | Add a progress note or comment to a task |

## PAT Scopes

Tokens can be scoped to limit access:

| Scope | Grants access to |
|-------|-----------------|
| `tasks:read` | get_active_tasks, list_tasks, get_task, search_tasks, find_related_tasks, get_follow_up_items, get_eisenhower_quadrant |
| `tasks:write` | create_task, update_task, complete_task, block_task, unblock_task |
| `goals:read` | get_active_goals, list_goals, get_goal |
| `goals:write` | create_goal, link_task_to_goal |
| `work:tracking` | start_working, stop_working, stop_all_work, get_current_work, get_work_summary |
| `comments:write` | add_comment |
| `collaborators:read` | list_collaborators, get_goal_collaborators, list_tasks_for_collaborator |

## Security

- Tokens are SHA-256 hashed at rest; the plaintext is shown only at creation
- Per-token rate limiting (120 requests/min)
- All mutations are logged in the Activity Log with revert support
- Tokens can be revoked anytime from Settings > API Access
- Secrets are redacted from error output

## License

MIT