npm package: @focuh/mcp-server
Description: MCP server for Focuh - manage todos, calendar, goals, and bottleneck analysis from Claude Desktop, Raycast, ChatGPT, and other MCP clients
Latest version: 1.6.0

# Focuh MCP Server

A Model Context Protocol (MCP) server that allows Claude Desktop, Raycast, Poke, and other MCP clients to manage your Focuh todos.

## Features

- **get_todos** - View today and tomorrow's tasks
- **create_todo** - Create new tasks with title, date, and time estimate
- **update_todo** - Update task title, estimate, or completion status
- **schedule_todo** - Schedule tasks to specific time slots
- **delete_todo** - Remove tasks

---

## Setup

### 1. Get Your API Key

1. Open Focuh in your browser
2. Click the **Settings** icon (gear) in the top right
3. Go to the **MCP** tab
4. Click **Generate API Key**
5. Copy the key (it's only shown once!)

### 2. Find Your Convex Site URL

Your Convex site URL is in the format: `https://<your-deployment>.convex.site`

You can find this in your Convex dashboard or in your app's environment variables.

---

## Configure Your AI Client

Choose your AI client below and follow the setup instructions:

<details>
<summary><strong>🖥️ Claude Desktop</strong></summary>

### Prerequisites

- Claude Desktop app installed ([download](https://claude.ai/download))
- macOS or Windows

### Step 1: Open the Configuration File

Locate and open your Claude Desktop configuration file:

| Platform | File Location |
|----------|---------------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |

> **Tip:** If the file doesn't exist, create it.

### Step 2: Add the Focuh MCP Server

Add the following configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "focuh": {
      "command": "npx",
      "args": ["-y", "@focuh/mcp-server"],
      "env": {
        "FOCUH_API_KEY": "focuh_your_key_here",
        "FOCUH_CONVEX_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

Replace:
- `focuh_your_key_here` with your actual API key
- `https://your-deployment.convex.site` with your actual Convex URL

<details>
<summary>Alternative: Running locally from source</summary>

If you're developing or running from the local mcp-server directory:

```json
{
  "mcpServers": {
    "focuh": {
      "command": "node",
      "args": ["/path/to/focuh/mcp-server/dist/index.js"],
      "env": {
        "FOCUH_API_KEY": "focuh_your_key_here",
        "FOCUH_CONVEX_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

</details>

### Step 3: Restart Claude Desktop

1. Completely quit Claude Desktop (not just close the window)
2. Reopen Claude Desktop
3. You should see **"focuh"** in the MCP tools list (click the 🔌 icon)

### Step 4: Test the Integration

Ask Claude: *"What are my todos for today?"*

If configured correctly, Claude will use the Focuh MCP to fetch your tasks.

</details>

<details>
<summary><strong>🌈 Raycast</strong></summary>

### Prerequisites

- [Raycast](https://raycast.com) installed on macOS
- Raycast Pro subscription (for AI features)

### Step 1: Install the MCP Extension

1. Open Raycast
2. Press `⌘ + ,` to open Preferences, or search for **"Store"**
3. Search for **"Model Context Protocol"**
4. Click **Install**

> **Reference:** [Raycast MCP Manual](https://manual.raycast.com/model-context-protocol)

### Step 2: Add the Focuh MCP Server

1. Open Raycast and search for **"Install Server"**
2. You can either fill out the form manually OR paste the JSON config below

**Option A: Paste JSON Config**

Copy this configuration before opening the Install Server command (Raycast will auto-fill the form):

```json
{
  "mcpServers": {
    "focuh": {
      "command": "npx",
      "args": ["-y", "@focuh/mcp-server"],
      "env": {
        "FOCUH_API_KEY": "focuh_your_key_here",
        "FOCUH_CONVEX_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

**Option B: Fill Out the Form Manually**

| Field | Value |
|-------|-------|
| **Name** | `focuh` |
| **Command** | `npx` |
| **Arguments** | `-y @focuh/mcp-server` |
| **Environment Variables** | `FOCUH_API_KEY=focuh_your_key_here` <br> `FOCUH_CONVEX_URL=https://your-deployment.convex.site` |

### Step 3: Use Focuh in Raycast AI

1. Open Raycast AI Chat (press `Tab` in Raycast)
2. Type `@focuh` to mention the MCP server
3. Ask questions like *"What are my todos for today?"*

### Managing MCP Servers

Search for **"Manage Servers"** in Raycast to view, edit, or remove installed MCP servers.

</details>

<details>
<summary><strong>🐣 Poke</strong></summary>

### Prerequisites

- [Poke](https://poke.app) app installed
- Your Focuh API key and Convex URL ready

### Step 1: Open Poke Settings

1. Open the Poke app
2. Navigate to **Settings**
3. Find the **MCP Servers** or **Connectors** section

### Step 2: Add the Focuh MCP Server

1. Click **Add Server** or **Add Custom Connector**
2. Enter the following details:

| Field | Value |
|-------|-------|
| **Name** | `Focuh` |
| **URL** | Your Convex site URL: `https://your-deployment.convex.site` |
| **API Key / Password** | Your Focuh API key: `focuh_your_key_here` |

3. Click **Save** to add the server

### Step 3: Test the Integration

1. Start a new chat in Poke
2. Ask *"What are my todos for today?"*
3. Poke should connect to Focuh and retrieve your tasks

> **Note:** The exact UI may vary based on your Poke version. Refer to Poke's documentation for the latest instructions.

</details>

<details>
<summary><strong>💬 ChatGPT</strong></summary>

### ⚠️ Important: Compatibility Notice

ChatGPT currently only supports **remote MCP servers** (HTTP/SSE transport), while the Focuh MCP server uses **local stdio transport**. This means **direct integration is not currently available**.

### What This Means

| Transport Type | Supported By | Focuh MCP |
|----------------|--------------|-----------|
| **stdio** (local) | Claude Desktop, Raycast, Cursor | ✅ Supported |
| **HTTP/SSE** (remote) | ChatGPT | ❌ Not yet supported |

### How ChatGPT MCP Works

For reference, here's how ChatGPT handles MCP servers (for when Focuh adds remote support):

#### Requirements
- ChatGPT Plus, Pro, Team, or Enterprise subscription
- ChatGPT Desktop app

#### Enable Developer Mode

1. Open ChatGPT
2. Click your **profile icon** (bottom left)
3. Go to **Settings** → **Connectors**
4. Scroll to **Advanced settings**
5. Toggle **Developer Mode** to **ON**

#### Adding a Remote MCP Server

1. In the **Connectors** section, click **Create a new connector**
2. Fill out the form:
   - **Name:** Your connector name
   - **MCP Server URL:** The remote server URL (must be HTTPS)
   - **Authentication:** Select the appropriate method (e.g., OAuth)
3. Click **Save**

> **Reference:** [OpenAI MCP Documentation](https://platform.openai.com/docs/mcp)

### Future Support

We're exploring options to provide a hosted remote MCP endpoint for ChatGPT users. Stay tuned for updates!

</details>

---

## Usage Examples

Once configured, you can ask your AI assistant to:

- *"Show me my todos for today"*
- *"Create a todo to review the quarterly report, estimate 45 minutes"*
- *"Schedule the quarterly report review for 2pm to 3pm"*
- *"Mark the quarterly report review as complete"*
- *"Add a todo for tomorrow: prepare presentation slides, 60 minutes"*

---

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FOCUH_API_KEY` | Yes | Your Focuh API key from Settings > MCP |
| `FOCUH_CONVEX_URL` | Yes | Your Convex site URL |

---

## Security

- API keys are stored as SHA-256 hashes in the database
- Keys are never logged or transmitted in plaintext (except once during generation)
- Each user has one API key; generating a new key invalidates the old one