🧭 Compass MCP

🧭 Compass MCP

The missing bridge between Claude Chat, Cowork, and Code.

Compass is an MCP server that gives Claude shared operational state across all three surfaces. Add a task in Chat, check it off in Code, filter by project in Cowork — same data, zero re-explaining.

┌───────────┐    ┌───────────┐    ┌───────────┐
│   Chat    │    │  Cowork   │    │   Code    │
└─────┬─────┘    └─────┬─────┘    └─────┬─────┘
      │                │                │
      └────────┬───────┴────────┬───────┘
               │                │
       ┌───────▼────────────────▼───────┐
       │         Compass MCP            │
       │                                │
       │   ┌──────────────────────┐     │
       │   │  ~/compass-data/     │     │
       │   │  tasks.md            │     │
       │   │  contexts/           │     │
       │   └──────────────────────┘     │
       └────────────────────────────────┘

Why?

Claude Chat, Cowork, and Code don't share state. Each session starts from zero. There's no way to ask in Chat "what did I finish in Code?" or tell Cowork "here's the context for this project" without re-explaining everything.

Compass fixes that. One MCP server, visible to all three surfaces, backed by plain markdown files.

This is not another todo app. It's the operational layer that connects how you think (Chat), how you execute (Cowork), and how you build (Code).

Install

git clone https://github.com/richlira/compass-mcp.git
cd compass-mcp
npm install
npm run build

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "compass": {
      "command": "node",
      "args": ["/absolute/path/to/compass-mcp/build/index.js"]
    }
  }
}

Restart Claude Desktop. All three tabs (Chat, Cowork, Code) will see Compass.

Usage

No commands to memorize. Just talk:

Works in English, Spanish, Spanglish — whatever. Claude matches your intent to the right tool automatically.

Tools

init_workspace

Creates ~/compass-data/ with tasks.md and contexts/ directory. Safe to run multiple times.

add_task

Adds a task to tasks.md.

• title (required) — what needs to be done
• tags — project or category tags (e.g. ["cancun", "marketing"])
• deadline — due date
• section — "active" (default) or "backlog"

complete_task

Marks a task as completed in tasks.md.

• title (required) — task to complete (fuzzy matched)
• notes — optional completion notes

get_tasks

Returns tasks filtered by status, tags, or deadline.

• status — "active", "backlog", "completed", or "all"
• tags — filter by tags
• deadline_before — show tasks due before a date

save_context

Creates or updates a project context file in contexts/.

• project (required) — project name (becomes the filename)
• content (required) — markdown content with project details

get_context

Reads a project context file.

• project (required) — project name to look up

Storage

Everything lives in ~/compass-data/:

~/compass-data/
├── tasks.md        ← all tasks with status, tags, deadlines
└── contexts/
    ├── cancun.md   ← project-specific context
    ├── workshop.md
    └── ...

Plain markdown. Human-readable. Git-versionable. No database.

The workspace path is configurable via the COMPASS_DATA_DIR environment variable.

How the three surfaces use Compass

Chat — your thinking space. Plan the day, add tasks, check status, save project context. Chat is where you decide.

Cowork — your execution space. Cowork reads the same tasks and contexts. It can check what's pending, mark things done as it works, and read project context to understand what to do.

Code — your building space. Code checks for build-related tasks, marks them complete when done, and reads project context for specs and decisions. Code is also where you maintain and improve Compass itself.

All three read and write the same tasks.md and contexts/ — that's the bridge.

Pro tip: combine with Google Calendar

If you have the Google Calendar connector enabled, Claude can combine Compass tasks with your calendar:

"Check my tasks and my calendar for today, and block time for what I can get done"

Claude reads your tasks from Compass, finds free slots in your calendar, estimates duration, and creates focus blocks. No extra code needed — just Claude orchestrating two tools together.

Requirements

• Node.js 18+
• Claude Desktop (macOS or Windows)
• Claude Pro, Max, Team, or Enterprise plan

Development

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

# Watch mode
npm run watch

Philosophy

Compass is intentionally minimal. Six tools, two file types, zero database. Decisions, progress tracking, and daily recaps are left to Claude's memory — that's what it's good at. Compass only handles what Claude can't do alone: queryable task state and structured project context that persists across all surfaces.

If you need more, add it. If you don't, enjoy the simplicity.

License

MIT

Chat, Cowork, Code — and Compass. 🧭