Cued MCP Server

MCP server for Cued — Enable Claude to access your local messages and contacts via Model Context Protocol.

Cued is a local-first message and contact datastore for AI agents. This MCP server bridges Cued and Claude, letting you:

• 🔍 Search messages across all platforms (iMessage, Discord, Gmail, Slack, etc.)

• 📋 Query contacts from your synchronized address book

• 🔄 Trigger platform syncs on-demand

• 📊 Get message statistics by platform

• 💾 Export conversations to JSON or CSV

• 🏥 Run diagnostics to verify installation and permissions

Everything stays local and private — data never leaves your Mac.

Installation

Via npm (Recommended)

npm install -g @cued/mcp

From Source

git clone https://github.com/Cue-d/mcp.git
cd mcp
npm install
npm run build

Related MCP server: imessage-mcp

Quick Start

1. Start the MCP Server

# Via CLI
cued-mcp start

# Or via Node.js
node /path/to/cued-mcp/dist/index.js

2. Configure Claude Code

Add to .claude/mcp.json:

{
  "mcpServers": {
    "cued": {
      "command": "node",
      "args": ["/path/to/cued-mcp/dist/cli.js"]
    }
  }
}

Replace /path/to/cued-mcp with your actual installation path. Find it with:

npm list -g @cued/mcp

3. Use in Claude

You: "Search my messages for 'project update' from the last week"
Claude: [Uses cued_search_messages tool]
→ Returns matching messages with context

CLI Usage

Start MCP Server

cued-mcp start
# or
cued-mcp server

Daemon Mode

Start Background Daemon

# Both PID-based and macOS launchd
cued-mcp daemon start both

# PID-based only (cross-platform)
cued-mcp daemon start pid

# macOS launchd only (native integration, auto-start)
cued-mcp daemon start launchd

Check Status

cued-mcp daemon status
# Output:
# [cued-mcp] PID daemon: running (PID: 12345)
# [cued-mcp] Launchd daemon: running

Stop Daemon

cued-mcp daemon stop both

View Logs

# Last 50 lines
cued-mcp daemon logs

# Last 100 lines
cued-mcp daemon logs 100

Available Tools

cued_status

Get current system status and health.

Claude: "Check my Cued status"
→ {healthy: true, database_path: "~/.cued/local.db", ...}

cued_integrations_status

View connected integrations and their sync status.

Claude: "What integrations do I have connected?"
→ {integrations: [{platform: "imessage", status: "idle", ...}, ...]}

cued_sync_run

Trigger a sync for a specific platform.

Claude: "Sync my Gmail"
→ Starts sync, returns status

Supported platforms: imessage, contacts, discord, gmail, slack, signal, whatsapp, linkedin

cued_search_messages

Search messages by text, platform, or date range.

Claude: "Find messages about 'quarterly review' from June"
→ [{id: "msg_123", from: "alice@...", body: "quarterly review...", ...}]

Parameters:

• query (required) — Search term

• platform — Filter by platform (e.g., "discord", "imessage")

• from — Unix timestamp (earliest date)

• to — Unix timestamp (latest date)

• limit — Max results (default: 10, max: 100)

• offset — Pagination offset

cued_get_contacts

Get contacts with pagination.

Claude: "Show me my top 20 contacts"
→ [{id: "...", name: "Alice", email: "alice@...", ...}]

Parameters:

• limit — Max results (default: 20, max: 100)

• offset — Pagination offset (default: 0)

cued_get_contacts_by_platform

Filter contacts by platform.

Claude: "Who are my Discord contacts?"
→ [{id: "...", name: "Bob", platform: "discord", ...}]

cued_message_stats

Get message count by platform.

Claude: "How many messages do I have per platform?"
→ {total: 12345, by_platform: {imessage: 5000, discord: 4000, ...}}

cued_get_thread

Get all messages in a conversation thread.

Claude: "Show me the full conversation thread with Alice"
→ [{id: "msg_1", from: "alice", ...}, {id: "msg_2", from: "me", ...}, ...]

cued_export_messages

Export messages to JSON or CSV format.

Claude: "Export my Discord messages as CSV"
→ Returns CSV file content as string

Formats: json, csv

cued_doctor

Run diagnostics and check system health.

Claude: "Run Cued diagnostics"
→ Detailed diagnostic report

Configuration

Environment Variables

# Optional: Require token for API access
export CUED_MCP_TOKEN="your-secret-token"

# Set to production for deployments
export NODE_ENV="production"

Programmatic Usage

import { startServer } from "@cued/mcp";

// Start the MCP server
await startServer();

Daemon Configuration

The daemon stores state in ~/.cued/:

• ~/.cued/mcp.pid — PID-based daemon process ID

• ~/.cued/mcp.log — Combined stdout/stderr logs

• ~/Library/LaunchAgents/com.cued.mcp.plist — macOS launchd configuration (macOS only)

Security & Privacy

✅ Local-first — All data stays in ~/.cued/local.db
✅ No cloud sync — Your messages never leave your Mac
✅ No external APIs — MCP server doesn't call third-party services
✅ User auth — Uses Cued's existing authentication and permissions
✅ Optional token auth — Add CUED_MCP_TOKEN for extra security

Requirements

• Node.js 18+

• Cued installed and configured

  • Check: cued doctor

• macOS (Cued is macOS-only for now)

Troubleshooting

"Command 'cued' not found"

Ensure Cued is installed:

cued doctor
which cued

If not installed, install Cued:

# Visit https://github.com/Cue-d/cued for installation instructions

Database query failed

Check database exists:

ls -la ~/.cued/local.db

Run Cued setup:

cued setup

MCP Server won't start

Check Node.js version:

node --version  # Need 18+

Check logs:

cued-mcp daemon logs 50

Permission denied errors

Ensure file permissions:

chmod 600 ~/.cued/local.db

Daemon won't stop

Kill manually:

# Find process
ps aux | grep cued-mcp

# Kill by PID
kill -9 <PID>

# Remove stale PID file
rm ~/.cued/mcp.pid

Development

Setup

git clone https://github.com/Cue-d/mcp.git
cd mcp
npm install

Build

npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm run lint           # Run ESLint
npm run lint:fix       # Auto-fix linting issues

Test

npm test               # Run all tests
npm run test:watch    # Watch mode

Local Development

# Start in watch mode
npm run dev

# In another terminal, test with Claude
claude mcp test cued

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• 🧪 Additional test coverage

• 📚 Documentation improvements

• ✨ New tools (e.g., message summarization, smart search)

• 🐛 Bug fixes

• ⚡ Performance improvements

Architecture

For technical details, see ARCHITECTURE.md.

High-Level Data Flow

Claude AI
    ↓
MCP Server (Node.js)
    ↓
├─→ Cued CLI (status, sync)
└─→ SQLite DB (~/.cued/local.db)
    ↓
Local Message/Contact Store (Private)

License

MIT — See LICENSE for details.

Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Cued Project: https://github.com/Cue-d/cued

Related

• Cued — Local-first message/contact datastore

• Model Context Protocol — MCP spec

• Claude API — Claude documentation

• Anthropic — Creator of Claude

Made with ❤️ for AI agents that respect your privacy.