oedmcp

The OED MCP Server provides an interface to look up words in the Oxford English Dictionary 2nd Edition data you supply. It exposes a set of MCP tools that let you fetch full dictionary entries, etymologies, perform prefix searches, request random words, and look up multiple words in one call. The server can operate over the standard MCP stdio transport and can also enable an HTTP transport (SSE) for web-based clients. If HTTP is enabled, you’ll access health, metrics, and MCP messages via endpoints such as /health, /metrics, /sse, and /message. Typical usage is to run the server with your OED2 data mounted and then point your MCP client (like Claude Desktop) to the server endpoint to start making requests.

Prerequisites:

• Go 1.21 or later (for building from source, if you choose to run directly without Docker)
• Legal access to OED2 data files (oed2 and oed2index) in Plan 9 format
• Docker (optional, for the provided containerized deployment)

Option A: Docker (recommended for quick start)

1. Ensure Docker is installed and running.
2. Prepare your data paths on the host and pass them via environment variables when starting the container:
   • OED_DATA_PATH=/path/to/your/oed2
   • OED_INDEX_PATH=/path/to/your/oed2index
   • Optionally set authentication env vars: OED_HTTP_AUTH_TYPE, OED_HTTP_AUTH_TOKEN
3. Run the container (example): docker run -i
   -e OED_DATA_PATH=/path/to/your/oed2
   -e OED_INDEX_PATH=/path/to/your/oed2index
   oedmcp:latest

Option B: Build from source (local run)

1. Clone the repository and navigate to it: git clone https://github.com/yourusername/oedmcp.git cd oedmcp
2. Build the server binary: go build -o oedmcp
3. Run the server with data paths configured (example): OED_DATA_PATH=/path/to/your/oed2 OED_INDEX_PATH=/path/to/your/oed2index ./oedmcp
4. If you want HTTP transport, pass the flags as described in the README (e.g., --enable-http --http-addr 127.0.0.1:7087).

Note: The README describes optional configuration via a Claude Desktop config file and various command-line options. Follow those details if you’re integrating with Claude Desktop or enabling HTTP transport.

Tips and common considerations:

• Ensure the OED data files are accessible and readable by the server process. Use absolute paths to avoid path resolution issues.
• In degraded mode, the server starts even if data files are unavailable, but lookups will fail with informative errors; this can be useful for containerized deployments where volumes may mount later.
• If enabling HTTP, you can secure endpoints with bearer or basic authentication as described in the README.
• Health and metrics endpoints (/health, /metrics) are useful for monitoring and can reflect the degraded status if data is missing.
• The available MCP tools are oed_lookup, oed_etymology, oed_search, oed_random, and oed_multi_lookup. Use the appropriate parameters (word, prefix, etc.).
• When using Docker, make sure the container has access to the host filesystem paths where oed2 and oed2index reside (via -v mounts if needed in your actual docker command).
• Remember: this server provides only the interface to licensed OED data you supply; it does not include the data itself.