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.

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.

| Variable | Default | What it does | | --- | --- | --- | | COSMOS_AUTHORIZATION | unset | The whole Authorization header value, Bearer and all. The credential; unlocks every A tool. | | COSMOS_COOKIE | unset | A full session-bearing Cookie header, if you have one. The AWSALB cookies alone are not enough. | | COSMOS_USER_ID | unset | Your numeric Cosmos user id. Optional; skips the me lookup on first use. | | COSMOS_ENDPOINT | https://api.cosmos.so/graphql | GraphQL endpoint. Override only for a mock or proxy. | | COSMOS_TIMEOUT_MS | 30000 | Per-request timeout in milliseconds. | | COSMOS_CLIENT_NAME | cosmos-web | Sent as x-client-name. The API rejects unknown clients; leave it alone. | | COSMOS_USER_AGENT | a desktop Chrome string | Sent as User-Agent. |

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

| Tool | What it does | | | --- | --- | :-: | | cosmos_search | Search every public element by keyword. Filter by content type and colour. | | | cosmos_search_clusters | Search public collections. Someone has often already built the board you want. | | | cosmos_search_users | Find people by name or handle. | | | cosmos_search_all | Search collections, people and elements at once. | | | cosmos_similar_elements | Give it one image you like; it returns images that look like it. | | | cosmos_element_saved_by | Which public collections hold an image, and who saved it. Finds people with the taste you want. | | | cosmos_browse_boards | Browse 800+ curated collections, by category if you pass one. | | | cosmos_conversational_search | Describe a brief in a sentence; get images grouped into named directions. Experimental. | A | | cosmos_explore | The featured feed. Pass a category to narrow it. | | | cosmos_spotlights | Editorial collections, such as "Rooms Lit Only by Lamps". | | | cosmos_categories | The 17 subject areas, such as Fashion and Interiors. | | | cosmos_suggested_searches | Search phrases Cosmos promotes. Thin signed out. | | | cosmos_cluster_recommendations | What Cosmos thinks belongs in a collection you already started. | A |

Read things

| Tool | What it does | | | --- | --- | :-: | | cosmos_get_element | One element in full: media, caption, source URL and author. | | | cosmos_get_cluster | One collection: name, owner, size, cover and subcollections. | | | cosmos_list_cluster_elements | Page through the elements in a collection. | | | cosmos_get_user | A public profile: bio, links and top collections. | | | cosmos_list_user_clusters | The collections on a profile. Partial list when signed out. | | | cosmos_view_images | Return elements as real images so the model can look at them. Costs tokens; pass few ids. | |

Build collections

| Tool | What it does | | | --- | --- | :-: | | cosmos_create_cluster | Create an empty collection. Private by default. | A | | cosmos_save_elements | Add elements to one collection. | A | | cosmos_save_url | Save an image or page from anywhere on the web. Returns the new element id. | A | | cosmos_organize_elements | Add and remove elements across collections in one call. | A | | cosmos_update_cluster | Rename a collection, or change its description, privacy or cover. | A | | cosmos_nest_cluster | Put a collection inside another, or pull it back out. | A | | cosmos_delete_cluster | Delete a collection. Permanent. Needs confirm: true. | A | | cosmos_find_clusters_for_element | Which of your collections an element can go in, and which already hold it. | A | | cosmos_quick_connect_suggestion | Ask Cosmos where an element belongs. | A |

Your account

| Tool | What it does | | | --- | --- | :-: | | cosmos_whoami | Report what the server can do now. Works signed out. Call it first. | | | cosmos_my_library | Everything you have saved. | A | | cosmos_list_my_clusters | Your collections, private ones included. | A | | cosmos_following_feed | Recent saves by the people you follow. | A | | cosmos_activity | Your notifications. | A | | cosmos_follow_user | Follow or unfollow a person. | A | | cosmos_follow_cluster | Follow or unfollow a collection. | A | | cosmos_pin_cluster | Pin one of your collections to your profile, or unpin it. | A |

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 r