npm package: @keyresults.io/mcp-server
Description: MCP server for KeyResults - manage goals, tasks, and projects from Claude Desktop
Author: KeyResults
Latest version: 0.2.1

# KeyResults MCP Server

MCP (Model Context Protocol) server for KeyResults, enabling Claude integration for managing goals, tasks, projects, weekly plans, and journal entries.

## Setup

### 1. Generate an API Key

1. Log into KeyResults at https://keyresults.io
2. Go to **Settings** > **API Keys**
3. Click "Create" and give your key a name (e.g., "Claude Desktop")
4. Copy the key immediately - you won't be able to see it again!

### 2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "keyresults": {
      "command": "npx",
      "args": ["-y", "@keyresults.io/mcp-server"],
      "env": {
        "KEYRESULTS_API_KEY": "kr_your_api_key_here",
        "KEYRESULTS_API_URL": "https://keyresults.io"
      }
    }
  }
}
```

Restart Claude Desktop and you'll have access to all KeyResults tools.

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `KEYRESULTS_API_KEY` | Yes | Your API key from Settings > API Keys |
| `KEYRESULTS_API_URL` | Yes | Your KeyResults URL (e.g., https://keyresults.io) |

## Available Tools

### Goals

| Tool | Description |
|------|-------------|
| `list_goals` | List all goals, optionally filtered by status |
| `get_goal` | Get a specific goal by ID |
| `create_goal` | Create a new goal (objective, key result, simple, or misogi) |
| `update_goal` | Update an existing goal |
| `delete_goal` | Delete a goal |

### Tasks

| Tool | Description |
|------|-------------|
| `list_tasks` | List tasks with filters (status, project, goal, week) |
| `get_task` | Get a specific task by ID |
| `create_task` | Create a new task |
| `update_task` | Update an existing task |
| `complete_task` | Mark a task as completed |
| `schedule_task` | Schedule a task to a specific date |
| `delete_task` | Delete a task |

### Projects

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects, optionally filtered by status |
| `get_project` | Get a specific project by ID |
| `create_project` | Create a new project |
| `update_project` | Update an existing project |
| `delete_project` | Delete a project and all its tasks |

### Weekly Plans

| Tool | Description |
|------|-------------|
| `get_weekly_plan` | Get the weekly plan for a specific week |
| `create_or_update_weekly_plan` | Create or update a weekly plan |

### Progress

| Tool | Description |
|------|-------------|
| `get_weekly_progress` | Get progress summary for a week |
| `get_week_comparison` | Compare task completion with previous week |

### Journal

| Tool | Description |
|------|-------------|
| `list_journal_entries` | List journal entries with filters (type, year, pagination) |
| `get_journal_entry` | Get a specific journal entry by ID |
| `create_journal_entry` | Create a new journal entry (journal, retrospective, reflection, gratitude, highlight) |
| `update_journal_entry` | Update an existing journal entry |
| `delete_journal_entry` | Delete a journal entry |

## Example Conversations

### Create a task
> "Create a task called 'Review Q1 OKRs' with high priority, due next Friday"

### Check progress
> "How many tasks did I complete this week compared to last week?"

### Plan the week
> "What are my active goals? Help me plan my week around them"

### Manage projects
> "Show me all active projects and their tasks"

### Journal
> "Create a journal entry about today's progress on the product launch"
> "Show me my gratitude entries from the last month"

## Development

### Build from source

```bash
# From the repository root
pnpm install
pnpm --filter @keyresults.io/mcp-server build
```

### Testing

You can test the server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node packages/mcp-server/dist/index.js
```

## Security

- Your API key is the only credential needed
- Keys can be revoked instantly from Settings > API Keys
- Keys can be temporarily deactivated without deletion
- Usage is tracked (last used time, total uses)
- All communication is over HTTPS