cosmos-mcp

MCP server for searching cosmos.so. Returns direct CDN image URLs — no page scraping.

Used by TVLR to find destination photos for places.json.

Install

git clone https://github.com/vihaanshahh/cosmos-mcp.git
cd cosmos-mcp
npm install

Related MCP server: Wikimedia-Search-Images

Cursor / Claude Code

{
  "mcpServers": {
    "cosmos": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cosmos-mcp/dist/index.js"]
    }
  }
}

Tools

search_images

{
  "query": "Tokyo skyline dusk",
  "limit": 10,
  "exclude_ai": true,
  "order": "RELEVANT",
  "color": "FF5500"
}

Returns results[].media_id, thumbnail_url, image_url, caption.

get_element

{ "element_id": 1169598936 }

Or pass a full share URL.

TVLR workflow

1. search_images({ query: "Porto azulejos tiles", exclude_ai: true })

2. Pick a result → copy UUID from CDN URL → set as cosmosId in places.json

3. URL pattern: https://cdn.cosmos.so/<cosmosId>?format=webp&w=800

Dev

npm run build
npm run dev

Notes

• No API key. Uses Cosmos's public GraphQL endpoint.

• Not an official Cosmos API — same backend the website uses.

• Typical search: ~300ms.

License

MIT