@cyanheads/datamuse-mcp-server

Overview

Word finding for writing, editing, puzzles, and naming, powered by the Datamuse API. Find a rhyme with a particular meaning, explore lexical alternatives, or combine meaning, sound, spelling, and relation constraints.

Tools

Results are linguistic suggestions, with sense-dependent and sometimes guessed metadata. They do not establish dictionary completeness or poetic suitability.

Related MCP server: Thesaurus By Api Ninjas

Capability reference

datamuse_find_rhymes tool

• Required word; rhyme_type is exact (default) or near. Optional means_like and spelled_like constrain the same search.

• English only. Exact searches never silently fall back to near rhymes.

datamuse_find_synonyms tool

• Required word; relation is synonyms (default), antonyms, broader, or narrower.

• English only. broader returns direct hypernyms; narrower returns direct hyponyms. Statistical associations are available through datamuse_find_words.

datamuse_find_words tool

• Supply at least one of means_like, sounds_like, spelled_like, or relations: [{ relation, word }]. Constraints form a conjunction; repeated relations are preserved, up to 14 entries.

• Relations: exact_rhyme, near_rhyme, synonyms, antonyms, broader, narrower, parts, wholes, nouns_modified_by, adjectives_describing, followers, predecessors, associated, homophones, consonant_match. Call datamuse_list_reference for their directions.

• Spelling supports upstream * and ? patterns. left_context, right_context, and up to five nonblank topics affect ordering; each must be a single word without commas. These hints alone cannot start a search.

• vocabulary is en (default) or es. Spanish supports meaning, sound, and spelling; relations require English.

datamuse_list_reference tool

• topic is all (default), relations, metadata, combinations, or limitations.

• Returns complete static sections without a network request.

Search results

All three search tools accept limit from 1–1000 (default 20) and include_definitions (default false). They return words in upstream order, plus effectiveQuery, returnedCount, limitReached, and any empty-result or cap notice.

Each row has word and any available score, numSyllables, tags, defs, defHeadword, and additional upstream JSON properties. Missing metadata stays absent. Tags and definitions remain raw, including unknown tags, tabs, and whitespace. f: tags express frequency per million words; scores rank results within one query and cannot be compared across queries.

Empty lists succeed. Reaching a limit means more matches may exist; there is no pagination, total-match count, or continuation token. A short list does not establish exhaustion. Every returned field is preserved in structured output and fenced JSON text.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Datamuse-specific:

• Live queries to Datamuse's fixed HTTPS word endpoint, without a local mirror or persistent query store.

• A shared process-local budget of one request per second and one in-flight request, with a bounded queue and retries. This conservative pacing does not guarantee a daily quota across processes or other users of the same egress address.

• Parts of speech, syllables, frequency tags, and optional definitions, preserving sparse responses and upstream ranking.

Agent-friendly output:

• Effective query and resolved defaults on every successful search, with actionable empty-result and cap guidance.

• Typed failures distinguish access, rate limits, malformed data, and upstream request errors. Upstream text is returned as data inside JSON fences.

Access, privacy, and attribution

Datamuse currently documents keyless access up to 100,000 requests per day and asks customer-facing applications to contact the provider. Its announced manually issued API-key transition has conflicting dates: the banner says February 1, 2027, while the usage section ends keyless access on January 1, 2027. Recheck the Datamuse documentation before either date. This server uses the current keyless API; no future credential format is documented or implemented, and the transition may interrupt access.

Queries leave this server and are sent to Datamuse, which says it temporarily logs them until the end of the following day. Server-level payload logging and telemetry are optional; review their settings before sending sensitive text.

Word results and lexical metadata are provided by Datamuse. See its documentation for contributing data sources and attribution requirements. The Apache-2.0 license covers this server's code; it does not grant additional rights to upstream data.

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "datamuse-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/datamuse-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "datamuse-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/datamuse-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "datamuse-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/datamuse-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• No Datamuse credentials currently required; see the access transition above.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/datamuse-mcp-server.git

2. Navigate into the directory:

cd datamuse-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env for transport, authentication, logging, or telemetry overrides

Configuration

See .env.example for every server setting and the common framework overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for logging, ctx.state for storage

• Register new tools and resources in the createApp() arrays in src/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.