# teampolarity/cosmos-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/teampolarity/cosmos-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 494  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/teampolarity-cosmos-mcp

## Description
Personal knowledge graph shared across MCP clients. Account-keyed and portable as a .polarity file, with sources for iMessage, browser history, calendar, Claude Desktop transcripts, shell history, Notion, and Obsidian. npx -y @polarity-lab/cosmos-mcp

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `COSMOS_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

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

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

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.

_Full upstream README: https://allmcps.com/mcp/teampolarity-cosmos-mcp/readme_