cosmos-mcp

cosmos-mcp

Build moodboards with an AI agent. cosmos-mcp is an unofficialModel Context Protocol server forcosmos.so, the visual discovery site. It gives Claude, Cursorand any other MCP client the ability to search Cosmos, find similar images, and savecollections to your account.

Search and browsing work with 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.

This project is not affiliated with, endorsed by, or supported by Cosmos. Read thisbefore you install it:

• Cosmos publishes no API and issues no API keys. This server calls the sameundocumented private GraphQL endpoint the cosmos.so web app uses. That endpoint canchange or disappear at any time, without warning, and this server will break when itdoes.
• Write access works by reusing your own browser session token (the Authorizationheader). There is no OAuth flow and no scoping. The token grants everything your accountcan do.
• You are responsible for complying with thecosmos.so Terms of Service. Use it with your ownaccount and your own data. Do not scrape.
• Use at your own risk, including the risk of account restrictions. See theLICENSE: no warranty.

What it does

On Cosmos, people save images, videos and products. Cosmos calls each saved item anelement. People group elements into collections. A collection can hold othercollections.

Cosmos calls a collection a cluster in its own API, so the tool names use that word:cosmos_get_cluster reads a collection. This page says "collection" throughout.

This server gives an AI 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.
5. Save the images that remain.

You do not open the site yourself. You describe what you want, and the agent builds themoodboard.

Who this is for

Designers, art directors and anyone who collects visual reference. 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

Claude Code

Command form:

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

With a token, so the write tools work:

claude mcp add cosmos -e COSMOS_AUTHORIZATION="Bearer paste-your-token-here" -- npx -y cosmos-mcp

JSON form, in .mcp.json at the root of your project:

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "cosmos-mcp"],
      "env": {
        "COSMOS_AUTHORIZATION": "Bearer paste-your-token-here"
      }
    }
  }
}

.mcp.json is checked into the repo by convention. If you put a token in it, add it to.gitignore first.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "cosmos-mcp"],
      "env": {
        "COSMOS_AUTHORIZATION": "Bearer paste-your-token-here"
      }
    }
  }
}

Restart Claude Desktop afterwards.

Cursor

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

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "cosmos-mcp"],
      "env": {
        "COSMOS_AUTHORIZATION": "Bearer paste-your-token-here"
      }
    }
  }
}

From a local clone, with Bun

git clone https://github.com/mrmos/cosmos-mcp.git
cd cosmos-mcp
bun install

Then point your client at it. Use absolute paths — MCP clients do not reliably resolverelative ones:

{
  "mcpServers": {
    "cosmos": {
      "command": "/opt/homebrew/bin/bun",
      "args": ["run", "/absolute/path/to/cosmos-mcp/index.ts"],
      "env": {
        "COSMOS_AUTHORIZATION": "Bearer paste-your-token-here"
      }
    }
  }
}

Or with Claude Code:

claude mcp add cosmos -- bun run /absolute/path/to/cosmos-mcp/index.ts

A local clone reads .env, so you can leave env out of the client config entirely.

Authentication

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

Cosmos has no API keys and no OAuth. The web app authenticates with a bearer token in theAuthorization header, so that is what this server reuses. (The Cookie header on thesame requests is only AWS load-balancer routing and will not sign you in.)

Sign in

npx cosmos-mcp login

It tells you how to copy the token, hides your input, checks it against cosmos.so, andsaves it only if it works. Then:

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

The credential goes in ~/.config/cosmos-mcp/config.json, written owner-only. Nothingprints it back.

You can pipe it instead, which suits a password manager:

pbpaste | npx cosmos-mcp login

Getting the token

login prints these steps too.

1. Open cosmos.so in a browser and sign in.
2. Open DevTools (Cmd+Option+I on macOS, F12 on Windows and Linux).
3. Go to the Network tab.
4. Reload the page, or click around until requests appear.
5. Click any request to api.cosmos.so.
6. Find Request Headers, then the Authorization header.
7. Copy the whole value. It begins with Bearer .

Do not copy the Cookie header instead — its AWSALB/AWSALBCORS values are load-balancerrouting and carry no identity, so they will not sign you in.

Other ways to configure it

login is the easy path. The server reads a credential from three places, and the firstone that has it wins:

1. The COSMOS_AUTHORIZATION environment variable, which is what an MCP client's envblock sets. (COSMOS_COOKIE is read too, for a full session-bearing cookie.)
2. A .env file next to the package. Useful when you cloned the repo.
3. ~/.config/cosmos-mcp/config.json, written by login.

Why not a password login?

Cosmos does have a password login mutation, and this server deliberately does not use it.Two reasons. It would put your Cosmos password through a third-party tool, where a sessiontoken is narrower and you can revoke it by signing out. And Cosmos rate-limits loginattempts, so scripted logins are the pattern its defences are built to catch.

Handling the token

• It is a credential. Treat it exactly like a password. Anyone holding it can act asyou on Cosmos.
• Never commit it. Not to .mcp.json, not to a dotfile repo, not to a screenshot inan issue.
• Do not paste it into a chat message. Put it in your MCP client's env block or ina local .env file. Pasting it into a conversation writes it into transcripts andsends it to a model provider.
• It expires. Sessions do not last forever. When the write tools start reporting"not signed in", go back to step 1 and paste 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, andwrites nothing to disk beyond the credential file you asked login to save.

Environment variables

Copy .env.example to .env for a documented starting point. Nothingis required.

Tools

Cosmos calls a collection a cluster, so the tool names do too.

A in the last column means the tool needs a credential (COSMOS_AUTHORIZATION).Everything else works signed out. Without one, an A tool returns an error that explainshow to fix it.

Find things

Read things

Build collections

Your account

Tools return JSON. They also fill structuredContent for clients that read it. Pagingworks the same everywhere: pass the nextCursor from one call as the cursor of thenext.

Example prompts

• "Build me a moodboard about warm brutalist interiors and save it to a new privatecollection."
• "Search Cosmos for 90s Japanese book covers, show me the twelve best as images, andsave the ones I pick to a collection called Type Refs."
• "Find this element on Cosmos, then pull twenty visually similar ones and tell me whatthe common thread is."
• "What's in my Colour Studies collection? Group it by dominant colour."
• "Look at the public collections of this user and summarise their taste in threesentences."
• "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 written to stdout that is not a JSON-RPCframe corrupts the protocol, so log to stderr.

To check the built artifact by hand:

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 containingserverInfo 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 and issues no API keys. It also turns off GraphQLintrospection. This server calls the same private endpoint the cosmos.so website calls.

Do I need an API key?

No. There are no API keys to get. Search and browsing need nothing. To save work to youraccount, you copy your own session token (the Authorization header) from the browser.See Authentication.

Does it work without signing in?

Yes. 18 of the 36 tools work signed out. You can search Cosmos, open collections, readpublic profiles and look at images before you configure anything.

Which MCP clients does it support?

Any client that speaks MCP over stdio. The install section covers Claude Code, ClaudeDesktop and Cursor.

Can this get my Cosmos account banned?

It uses a private API, so there is some risk. Cosmos does not promise this endpoint toanyone. Use it with your own account, at a normal pace, and read thedisclaimer.

Will it break?

Probably, one day. Cosmos can change the endpoint at any time and owes no notice. SeeCONTRIBUTING.md for how to check an operation against the live API andsend a fix.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md —please read the part about verifying a GraphQL operation against the live API beforeadding one.

License

MIT. See LICENSE.

Not affiliated with or endorsed by Cosmos.