pdfinn/oedmcp

OED MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Oxford English Dictionary 2nd Edition. This allows Claude and other MCP-compatible AI assistants to look up word definitions, etymologies, and historical usage directly from the OED.

⚠️ Important Legal Notice

This software does not include any OED data. The Oxford English Dictionary is proprietary content owned by Oxford University Press. You must have legal access to OED2 data files to use this server. This project only provides the interface to read properly licensed OED data that you provide.

Features

• 🔍 Word Lookup: Full dictionary entries with pronunciations, definitions, and quotations
• 📚 Etymology Search: Detailed word origins and historical development
• 🔤 Prefix Search: Find words starting with specific prefixes
• 🎲 Random Word: Discover random dictionary entries
• 📦 Batch Lookup: Look up multiple words simultaneously
• 🌐 Dual Transport: Supports both stdio (MCP) and HTTP/SSE transports simultaneously
• 🏥 Health Monitoring: Built-in health check and metrics endpoints
• 🔒 Authentication: Optional bearer token or basic auth for HTTP endpoints
• 💪 Degraded Mode: Continues running even if dictionary files unavailable

Prerequisites

• Go 1.21 or later
• Legal access to OED2 data files in Plan 9 format:
  • oed2 - Main data file (~520 MB)
  • oed2index - Index file (~5.6 MB)
• Claude Desktop or another MCP-compatible client

Installation

1. Clone the Repository

git clone https://github.com/yourusername/oedmcp.git
cd oedmcp

2. Configure Data Paths

The server needs to know where your OED data files are located. You can configure this in several ways (in order of priority):

Option A: Environment Variables

export OED_DATA_PATH=/path/to/your/oed2
export OED_INDEX_PATH=/path/to/your/oed2index

Option B: Configuration File

Copy the example configuration and edit it:

cp oed_config.example.json oed_config.json

Edit oed_config.json:

{
  "data_path": "/path/to/your/oed2",
  "index_path": "/path/to/your/oed2index"
}

Option C: User Home Directory

Create a configuration in your home directory:

mkdir -p ~/.oed_mcp
cp oed_config.example.json ~/.oed_mcp/config.json
# Edit ~/.oed_mcp/config.json with your paths

3. Build the Server

go build -o oedmcp

Or use the provided build script:

./build.sh

4. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Add this to your mcpServers section:

{
  "mcpServers": {
    "oed": {
      "command": "/absolute/path/to/oedmcp",
      "env": {
        "OED_DATA_PATH": "/path/to/your/oed2",
        "OED_INDEX_PATH": "/path/to/your/oed2index"
      }
    }
  }
}

5. Restart Claude Desktop

The OED tools will be available after restarting Claude Desktop.

Command-Line Options

The OED MCP server supports the following command-line flags:

./oedmcp [options]

Transport Options

Examples

Stdio only (default - for Claude Desktop):

./oedmcp

Dual transport (stdio + HTTP for monitoring):

./oedmcp --enable-http --http-addr 127.0.0.1:7087

With bearer token authentication:

export OED_HTTP_AUTH_TOKEN="your-secret-token"
./oedmcp --enable-http --http-auth-type bearer

With basic authentication:

export OED_HTTP_AUTH_USER="admin"
export OED_HTTP_AUTH_PASS="password"
./oedmcp --enable-http --http-auth-type basic

Bind to all interfaces (use with caution):

./oedmcp --enable-http --http-addr 0.0.0.0:7087

HTTP Endpoints

When --enable-http is enabled, the following endpoints are available:

Health Check Response Example:

{
  "status": "healthy",
  "service": "oedmcp",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "connections": {
    "data_file": {
      "status": "connected",
      "path": "/path/to/oed2",
      "size_mb": 520.5,
      "readable": true,
      "last_error": null
    },
    "index_file": {
      "status": "connected",
      "path": "/path/to/oed2index",
      "size_mb": 5.6,
      "readable": true,
      "last_error": null
    }
  }
}

Degraded Mode

If dictionary data files are unavailable at startup, the server will start in degraded mode:

• Server process starts successfully (doesn't fail)
• Health endpoint returns "status": "degraded"
• MCP tool calls return informative errors
• Allows monitoring systems to detect the issue without blocking entire stack

This is particularly useful in containerized or distributed deployments where the server should start even if data volumes aren't yet mounted.

Usage

Once configured, you can ask Claude to look up words:

• "Look up 'serendipity' in the OED"
• "What's the etymology of 'computer'?"
• "Search for words starting with 'astro'"
• "Give me a random word from the OED"
• "Look up 'cat', 'dog', and 'bird' in the dictionary"

Available MCP Tools

Data Format

This server works with OED2 data in Plan 9 dictionary format. The data files should be:

• oed2: Binary data file containing dictionary entries with embedded XML-style tags
• oed2index: Tab-separated index file with format: word[TAB]offset

The server parses OED2's tag format including:

• <hw>...</hw> - Headwords
• <etym>...</etym> - Etymology
• <pr>...</pr> - Pronunciation
• Various other semantic and formatting tags

Development

Project Structure

oedmcp/
├── main.go              # MCP server implementation
├── dict/
│   └── oed.go          # Dictionary access layer
├── config/
│   └── config.go       # Configuration management
├── go.mod              # Go module definition
└── go.sum              # Go module checksums

Testing

Create a test configuration:

cp oed_config.example.json oed_config.json
# Edit with your data paths

Run tests:

go test ./...

Test the server directly:

# Initialize and test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | ./oedmcp

Troubleshooting

Server won't start

• Verify OED data files exist at configured paths
• Check file permissions (must be readable)
• Ensure paths are absolute, not relative

No results from lookups

• Verify the index file matches the data file
• Check that both files are from the same OED2 version
• Try a known common word like "dictionary" or "cat"

Etymology not showing

• Ensure you're using include_etymology: true in lookup
• Some entries may not have etymology information

Contributing

Contributions are welcome! Please note:

• Do NOT commit any OED data files
• Keep data paths configurable
• Maintain compatibility with MCP protocol
• Add tests for new features

License

This project is licensed under the MIT License - see the file for details.

Important: This license applies only to the server code, not to any OED data. The OED remains the intellectual property of Oxford University Press.

Acknowledgments

• Based on Plan 9's dictionary format and tools
• Uses the mcp-go library
• Inspired by the original Plan 9 dict implementation

Disclaimer

This project is not affiliated with, endorsed by, or connected to Oxford University Press or the Oxford English Dictionary. Users must ensure they have appropriate rights to use OED data files with this software.