# Sketch Engine MCP Server

A tool that connects Claude (AI assistant) to Sketch Engine, enabling powerful corpus linguistics and text analysis directly in your conversations with Claude.

![alt text](docs/claude.gif)

![alt text](docs/claude-output.png)

## What is This?

This server lets Claude access Sketch Engine's massive text databases (corpora) to help you with linguistic research, language learning, writing, and text analysis. You can ask Claude questions like:

- "What are the most common collocations with 'artificial intelligence'?"
- "Show me how the word 'literally' is used in modern English"
- "Compare how 'affect' and 'effect' are used in academic writing"

Claude will use Sketch Engine's tools to give you detailed, corpus-based answers.

## Quick Start

**No technical knowledge required!** Just download, configure, and go.

### Step 1: Download

Download the standalone executable for your system from the [releases page](https://github.com/ricCap/sketch-engine-mcp-server/releases):

- **Linux**: `sketch-engine-mcp-linux-x64`
- **macOS (Intel)**: `sketch-engine-mcp-macos-x64`
- **macOS (Apple Silicon/M1/M2/M3)**: `sketch-engine-mcp-macos-arm64`
- **Windows**: `sketch-engine-mcp-win-x64.exe`

**No installation needed!** These are standalone executables that work out of the box.

#### For Linux/macOS: Make it executable

After downloading, open Terminal and run:

```bash
chmod +x sketch-engine-mcp-linux-x64
```

(Replace with your actual filename)

### Step 2: Get Your Sketch Engine API Key

You need a free Sketch Engine account:

1. Go to [https://www.sketchengine.eu](https://www.sketchengine.eu)
2. Click **"Register"** to create a free account (or log in if you have one)
3. After logging in, click your **username** in the top-right corner
4. Select **"My Account"**
5. Find the **"API Key"** section
6. Click **"Generate API Key"** if you don't have one
7. **Copy your API key** - you'll need it in the next step

**Keep this key private!** It's like a password for your Sketch Engine account.

### Step 3: Configure Claude

You need to tell Claude about this server. Don't worry - it's just editing one configuration file.

#### Find Your Config File

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

**Tip for macOS/Linux**: Open Terminal and run:

```bash
mkdir -p ~/.config/Claude  # Create directory if needed
nano ~/.config/Claude/claude_desktop_config.json  # Edit file
```

#### Add This Configuration

Copy and paste this into the config file:

```json
{
  "mcpServers": {
    "sketch-engine": {
      "command": "/path/to/sketch-engine-mcp-linux-x64",
      "env": {
        "SKETCH_ENGINE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Replace two things:**

1. `/path/to/sketch-engine-mcp-linux-x64` - The full path to where you downloaded the executable
2. `your_api_key_here` - Your actual API key from Step 2

**Example (macOS):**

```json
{
  "mcpServers": {
    "sketch-engine": {
      "command": "/Users/yourname/Downloads/sketch-engine-mcp-macos-arm64",
      "env": {
        "SKETCH_ENGINE_API_KEY": "abc123xyz789"
      }
    }
  }
}
```

Save the file and restart Claude Desktop (or Claude Code CLI).

### Step 4: Try It Out!

Open Claude and try these example questions:

```
"Use Sketch Engine to list available corpora"
```

```
"Find collocations for 'climate change' in the EnTenTen21 corpus"
```

```
"Show me concordances for the word 'serendipity'"
```

If it works, you'll see Claude using the Sketch Engine tools to answer your questions!

## What Can You Do?

This server gives Claude access to these Sketch Engine tools:

### Core Analysis Tools

- **Word Sketches**: See how words are typically used (grammatical patterns, collocations)
- **Concordances**: Find real examples of words or phrases in context
- **Word Lists**: Generate frequency lists of words in any corpus
- **Word Comparison**: Compare how two similar words are used differently
- **Collocations**: Find words that commonly appear together

### Advanced Tools

- **Frequency Analysis**: Analyze how often words/phrases appear
- **Keyword Extraction**: Find characteristic words by comparing two corpora
- **Custom Queries**: Run advanced searches using CQL (Corpus Query Language)

### Examples of What You Can Ask Claude

```
"Compare the usage of 'effect' and 'affect' in academic English"
```

```
"What are the most common adjectives used with 'solution'?"
```

```
"Find examples of 'literally' being used in the EnTenTen corpus"
```

```
"Generate a word frequency list for the Susanne corpus"
```

```
"Show me concordances for 'break * ice' (phrasal pattern)"
```

For more detailed examples and workflows, see **[docs/EXAMPLES.md](docs/EXAMPLES.md)**.

## Troubleshooting

### "Command not found" or "No such file"

- Check that the path in your config file is correct (use full absolute path)
- On Linux/macOS, make sure you ran `chmod +x` on the executable

### "Invalid API key" or "Authentication failed"

- Double-check that you copied your API key correctly from Sketch Engine
- Make sure there are no extra spaces in the config file

### Claude doesn't show Sketch Engine tools

- Restart Claude Desktop (or Claude Code CLI)
- Check that your config file JSON is valid (use a JSON validator online if needed)

### Still having issues?

- See the detailed **[User Guide](docs/USER_GUIDE.md)** for step-by-step instructions with screenshots
- Report issues on [GitHub](https://github.com/ricCap/sketch-engine-mcp-server/issues)

## For Developers

If you want to build from source, contribute, or understand how this works:

- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Complete development guide
- **[CLAUDE.md](CLAUDE.md)** - AI assistant development instructions

## About Sketch Engine

[Sketch Engine](https://www.sketchengine.eu) is a leading corpus management and text analysis tool used by linguists, lexicographers, translators, and language learners worldwide. It provides access to massive text databases (corpora) in 90+ languages.

## License

See LICENSE file for details.