cosmos-mcp

Build moodboards with an AI agent. cosmos-mcp is an unofficial Model Context Protocol server for cosmos.so, the visual discovery site. It lets Claude, Cursor and any other MCP client search Cosmos, find similar images, and save collections to your account.

Search and browsing need no setup. You add a token only when you want to save.

One command for Claude Code:

claude mcp add cosmos -- npx -y cosmos-mcp

Unofficial. Not affiliated with Cosmos.

Read this before you install:

• Cosmos publishes no API. This server calls the same private GraphQL endpoint the cosmos.so web app uses. Cosmos can change or remove that endpoint at any time, and this server will break when it does.

• Write access reuses your own browser session token (the Authorization header). There is no OAuth and no scoping: the token can do everything your account can.

• You are responsible for the cosmos.so Terms of Service. Use your own account and your own data. Do not scrape.

• Use at your own risk, including the risk of account restrictions. The LICENSE gives no warranty.

Related MCP server: pinterest-vision-mcp

What it does

On Cosmos, people save images, videos and products. Each saved item is an element. Elements are grouped into collections, which can nest. Cosmos calls a collection a cluster in its API, so the tool names use that word; this page says "collection".

The server gives an agent tools for that model. In one turn, an agent can:

1. Search Cosmos for "warm brutalist interiors".

2. Find images that look like the best result.

3. Look at each image and reject the weak ones.

4. Create a collection and save the keepers.

You describe what you want. The agent builds the moodboard.

It suits three jobs:

• Research: find reference for a brief without clicking through a site.

• Curation: sort saved work into collections and move elements between them.

• Discovery: start from one image you like and find more like it.

Install

For Claude Code:

claude mcp add cosmos -- npx -y cosmos-mcp

Add -e COSMOS_AUTHORIZATION="Bearer paste_your_token_here" to enable the write tools, or run npx cosmos-mcp login later (see Authentication).

Every other client uses the same JSON config:

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "cosmos-mcp"],
      "env": {
        "COSMOS_AUTHORIZATION": "Bearer paste_your_token_here"
      }
    }
  }
}

Where to put it:

• Claude Code: .mcp.json at your project root. This file is usually committed, so keep tokens out of it: use claude mcp add -e, login, or .gitignore it.

• Claude Desktop: claude_desktop_config.json, at ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows. Restart the app afterwards.

• Cursor: ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

Leave out the env block if you only want search and browsing, or if you signed in with login.

From a local clone

Requires Bun:

git clone https://github.com/mrmos/cosmos-mcp.git
cd cosmos-mcp
bun install
claude mcp add cosmos -- bun run /absolute/path/to/cosmos-mcp/index.ts

Use absolute paths: MCP clients do not reliably resolve relative ones. A local clone reads .env, so you can leave env out of the client config.

Authentication

Skip this until you want to save something. Every tool without an A in the Tools tables works right now.

Cosmos has no API keys and no OAuth. The web app authenticates with a bearer token in the Authorization header, so this server reuses yours.

Sign in

npx cosmos-mcp login

It walks you through copying the token, hides your input, verifies it against cosmos.so, and saves it only if it works. The credential goes in ~/.config/cosmos-mcp/config.json, written owner-only, and is never printed back. You can also pipe it in from a password manager: pbpaste | npx cosmos-mcp login.

npx cosmos-mcp status    # which credential is in use, and whether it still works
npx cosmos-mcp logout    # remove it

To copy the token (login prints these steps too):

1. Sign in at cosmos.so, then open DevTools (Cmd+Option+I on macOS, F12 elsewhere).

2. In the Network tab, reload the page and click any request to api.cosmos.so.

3. Under Request Headers, copy the whole Authorization value. It begins with Bearer .

Do not copy the Cookie header: its AWSALB values are load-balancer routing and will not sign you in.

The server reads a credential from three places; the first one wins:

1. The COSMOS_AUTHORIZATION environment variable, set by an MCP client's env block.

2. A .env file next to the package, for local clones.

3. ~/.config/cosmos-mcp/config.json, written by login.

Handling the token

Treat it like a password: anyone holding it can act as you on Cosmos.

• Never commit it, not to .mcp.json, a dotfile repo, or a screenshot.

• Don't paste it into a chat message. That writes it into transcripts and sends it to a model provider. Use the env block, .env, or login instead.

• It expires. When write tools report "not signed in", copy a fresh one.

• Revoke it by signing out of that browser session on cosmos.so.

The token is sent to api.cosmos.so and nowhere else. This server has no telemetry and writes nothing to disk beyond the credential file login saves.

Why no password login? Cosmos has a login mutation, but using it would put your password through a third-party tool, and Cosmos rate-limits login attempts: scripted logins are exactly what its defences catch. A session token is narrower and revocable.

Environment variables

Copy .env.example to .env for a documented starting point. Nothing is required.

Tools

A means the tool needs a credential (COSMOS_AUTHORIZATION). Everything else works signed out. Without a credential, an A tool returns an error that explains the fix.

Find things

Read things

Build collections

Your account

Tools return JSON and fill structuredContent for clients that read it. Paging works the same everywhere: pass the nextCursor from one call as the cursor of the next.

Example prompts

• "Build me a moodboard about warm brutalist interiors and save it to a new private collection."

• "Search Cosmos for 90s Japanese book covers, show me the twelve best as images, and save the ones I pick to a collection called Type Refs."

• "Find this element on Cosmos, then pull twenty visually similar ones and tell me the common thread."

• "What's in my Colour Studies collection? Group it by dominant colour."

• "Look at this user's public collections and summarise their taste in three sentences."

• "Take everything I saved this week and file it into the right existing collection."

Development

Requires Bun.

bun install          # install dependencies
bun run dev          # run the server from source, restarting on change
bun test             # run tests
bun run typecheck    # tsc --noEmit
bun run build        # bundle to dist/index.js for Node

The server speaks MCP over stdio. Anything on stdout that is not a JSON-RPC frame corrupts the protocol, so log to stderr.

To smoke-test the built artifact:

bun run build
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n' \
  | node dist/index.js

You should see cosmos-mcp ready on stdio on stderr and a JSON-RPC result containing serverInfo on stdout.

Project layout

index.ts                 entrypoint: stdio transport
src/
  config.ts              environment variables to CosmosConfig
  errors.ts              CosmosError, and the mapping from GraphQL codes to kinds
  normalize.ts           API shapes to the flatter shapes tools return
  server.ts              McpServer construction and tool registration
  graphql/
    client.ts            HTTP client, auth headers, viewer resolution
    fragments.ts         shared GraphQL fragments
  tools/
    kit.ts               shared helpers: ok/fail/guard, common arguments
    account.ts           whoami, library, feed, activity
    browse.ts            search, explore, elements, users, clusters
    curate.ts            create, save, organise
scripts/
  probe-schema.ts        schema discovery against the live API
docs/
  har-ops/               reverse-engineered GraphQL operation reference
test/

See docs/README.md for where the operation reference came from.

Questions

Does cosmos.so have an API? No. Cosmos publishes no public API, issues no API keys, and turns off GraphQL introspection. This server calls the same private endpoint the website calls.

Do I need an API key? No, there are none to get. Search and browsing need nothing. To save, copy your own session token from the browser: see Authentication.

Does it work without signing in? Yes. 18 of the 36 tools work signed out: search, collections, public profiles, images.

Which MCP clients does it support? Any client that speaks MCP over stdio.

Can this get my account banned? There is some risk; Cosmos promises this endpoint to no one. Use your own account at a normal pace, and read the disclaimer.

Will it break? Probably, one day, when Cosmos changes the endpoint. CONTRIBUTING.md explains how to check an operation against the live API and send a fix.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md, especially the part about verifying a GraphQL operation against the live API before adding one.

License

MIT. See LICENSE.

Not affiliated with or endorsed by Cosmos.