Cosmos MCP

What teampolarity/cosmos-mcp MCP server does

The teampolarity/cosmos-mcp MCP server gives MCP-capable applications access to a shared Cosmos knowledge graph. The graph is associated with a user account and can be exported as a portable .polarity file. Multiple clients can read from and write to the same graph instead of maintaining separate agent-specific context.

The server exposes eleven tools. Read operations identify the bound user and scopes, return graph data at different entity levels, export the complete personal graph, or answer natural-language questions using graph contents. Write operations accept observations, events, preferences, full conversation turns, short location-based messages, check-ins, future presence declarations, and reconstructed work-hour records.

Use this server when context needs to follow a user between supported MCP clients such as Claude Desktop, Cursor, Codex, Zed, or Continue. It is also relevant when existing personal data should become graph source material rather than remain isolated in individual applications.

How it works

The MCP client runs the package through npx and communicates with the Cosmos service using an account key. A client can submit a freeform observation, a typed event or preference, or an entire user-assistant exchange. The latter lets Cosmos extract durable observations from a conversation in one request.

Read tools expose the resulting graph through API-backed operations. polarity_get_graph can scope its view to the user, Cosmos, or Polarity entities, while polarity_ask sends a natural-language question for synthesis over the graph. polarity_export returns the full graph in the polarity/v1 JSON format.

The package also includes source-specific CLI commands. On macOS, iMessage data is read locally from the Messages database after Full Disk Access is granted; only normalized conversation turns are sent to the graph. Shell-history sync reads local shell history with a byte-offset watermark, filters trivial commands and consecutive duplicates, and uploads each sync window as a source page. Claude Code session transcripts under ~/.claude/projects/ can also be synchronized. Notion uses OAuth and Obsidian uses a community plugin.

Setup and configuration

The documented MCP command is:

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "@polarity-lab/cosmos-mcp"]
    }
  }
}

Authentication can be provisioned through the Cosmos website and stored in the macOS system keychain, or supplied manually with a pmk_ key. The init command opens a browser-based sign-in flow and stores the token at ~/.config/cosmos-mcp/token. For CI, set COSMOS_TOKEN; this takes precedence over the keychain. The install-handler provisioning flow is macOS-only.

The repository also documents a shell installer that configures common clients. On macOS, that installer can register the cosmos-mcp:// scheme and install Cosmos Sync for background source synchronization. Linux and Windows receive the MCP server path only.

Tools and capabilities

The teampolarity/cosmos-mcp MCP server includes these supported capabilities:

• Check the authenticated account with polarity_whoami.
• Export or inspect graph data with polarity_export and polarity_get_graph.
• Ask natural-language questions with polarity_ask.
• Store observations, events, and preferences.
• Capture a complete conversation turn for durable-knowledge extraction.
• Record reconstructed work-hour receipts, location dumps, check-ins, and declarations.
• Synchronize supported local and connected sources into the same graph.

Limitations and notes

Local source access depends on the operating system and permissions. iMessage synchronization is macOS-only and requires Full Disk Access for the application running the CLI. The automatic URL-handler provisioning flow is also macOS-only. Linux and Windows support the MCP server path, but the excerpt does not document equivalent local-source setup for those platforms.

Notion requires connecting through the Cosmos connectors page, and Obsidian requires the Polarity community plugin. The server is one write path into Cosmos; source pages may also be supplied by other integrations or the direct API. Re-synchronization skips unchanged pages, and iMessage synchronization uses an incremental watermark after its initial window.