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:

Prerequisites

• Claude Desktop app installed (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:

{
  "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

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

{
  "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"
      }
    }
  }
}

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.

Prerequisites

• Raycast 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

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

{
  "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 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.

Prerequisites

• Poke 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.

⚠️ 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

Future Support

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

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

# 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