# teampolarity/cosmos-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/teampolarity/cosmos-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 655  
**Views:** 3  
**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. 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:

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

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