Skip to main content
Glama
vihaanshahh

cosmos-mcp

by vihaanshahh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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: unsplash-mcp

Cursor / Claude Code

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

Tools

Tool

What it does

search_images

Search by keyword. Filter by color, content type, sort order.

search_collections

Search curated boards.

get_element

Look up one element by ID or cosmos.so/e/... URL.

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

Available Tools

3 tools
get_elementA

Fetch a single cosmos.so element by ID or share URL. Returns the image URL, caption, source link, and owner.

ParametersJSON Schema
NameRequiredDescriptionDefault
element_idYesElement ID (e.g. 2019059012) or cosmos.so URL (e.g. https://www.cosmos.so/e/2019059012).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes the fetch operation and return fields but lacks details on error handling, rate limits, or authentication. Adequate for a simple read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with clear purpose and output. No wasted words, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one param and no output schema; description covers purpose, input, and output adequately. Lacks error handling but sufficient for context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage, but description adds value by listing return fields (image URL, caption, etc.) not in schema, enhancing parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a single element by ID or URL, listing return fields. It distinguishes from sibling search tools which are for broader queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you have a specific element ID or URL, but does not explicitly state when not to use or mention alternative tools for other scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_collectionsA

Search cosmos.so curated collections (thematic boards of saved elements). Returns collection names, cover images, element counts, and follower counts.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoResults per page (1-100). Defaults to 20.
queryYesSearch term for collection names and topics.
page_cursorNoPagination cursor from a previous response's next_page_cursor field.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description mentions return fields (names, cover images, counts, followers) but does not disclose pagination behavior, rate limits, or read-only nature. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence conveying purpose and output without extraneous words. Perfectly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters and no output schema, the description is sufficiently complete for a search tool. Could mention pagination but schema already handles that. Overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and describes each param. Description adds value by explaining what collections are ('thematic boards of saved elements') and what is returned, enriching understanding of the query parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'search' and resource 'collections'. Distinguishes from sibling tools 'get_element' (gets single element) and 'search_images' (searches images) by specifying it searches curated collections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use versus alternatives, but the description implies usage for finding collections. Implied from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_imagesA

Search cosmos.so for images and visual elements. Returns direct CDN image URLs, captions, and metadata without loading web pages. Fast structured results for mood boards, design research, and visual inspiration.

ParametersJSON Schema
NameRequiredDescriptionDefault
colorNoFilter by dominant color as hex without #, e.g. 'FF0000' for red.
limitNoResults per page (1-40). Defaults to 20.
orderNoSort order. Defaults to RELEVANT.
queryYesSearch term, e.g. 'brutalist architecture', 'editorial typography', 'earth tones'
exclude_aiNoWhen true, filters out AI-generated images client-side.
page_cursorNoPagination cursor from a previous response's next_page_cursor field.
content_typeNoFilter by element type. Defaults to IMAGE.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses return types (CDN URLs, captions, metadata) and mentions 'fast structured results', but does not cover pagination behavior, required permissions, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is just two sentences with no wasted words. First sentence states purpose, second sentence adds value proposition. Well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, but the description covers key return elements (CDN URLs, captions, metadata). It lacks explicit mention of pagination or empty result handling, but overall it is reasonably complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add any extra meaning beyond the schema; no parameter-specific elaboration is given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'images and visual elements'. It specifies what is returned (CDN URLs, captions, metadata) and adds 'without loading web pages' to differentiate from web scraping. However, it does not explicitly distinguish from sibling tools like 'get_element' or 'search_collections'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for use cases ('mood boards, design research, and visual inspiration'), implying when to use. However, it does not explicitly state when not to use or mention any alternative tools among the siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedget_element
    • First observedsearch_collections
    • First observedsearch_images
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: retrieving a specific element by ID/URL, searching collections, and searching images. There is no overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case: get_element, search_collections, search_images. No naming style variations.

Tool Count4/5

With 3 tools, the set is slightly minimal but covers core retrieval and search operations for the cosmos.so domain. It feels appropriately scoped for a read-only search API.

Completeness3/5

The tools are read-only (get and search), lacking create, update, or delete operations for elements or collections. This is a notable gap if full lifecycle management is expected, but it may be sufficient for a search-focused tool.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers