# Jisho MCP

A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Jisho.org](https://jisho.org), the popular Japanese-English dictionary.

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/FastMCP-2.0+-orange.svg" alt="FastMCP 2.0+">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT">
</p>

<p align="center">
  <img src="assets/tanuki.png" alt="Tanuki mascot" width="300">
</p>

Look up Japanese words, readings, JLPT levels, and definitions directly inside MCP-compatible AI clients — or let your agent search for you.

## Features

- Word search with all Jisho filters (`#jlpt-n5`, `#verb`, wildcards, etc.)
- Exact lookup by word slug (e.g. `食べる`)
- Compact responses (Wikipedia/dbpedia padding stripped, linguistic fields like `see_also`, `antonyms`, `source` preserved)
- Read-only resources: `jisho://word/{keyword}` and `jisho://search/{keyword}`

## Quick start

No installation required. You only need [uv](https://docs.astral.sh/uv/) and Python >= 3.10.

### Claude Code

```bash
claude mcp add jisho -- uvx --from git+https://github.com/giuliocapecchi/jisho-mcp jisho-mcp
```

### Other MCP clients (Claude Desktop, Codex, OpenCode, …)

Add the following block to your client's MCP config file:

```json
{
  "mcpServers": {
    "jisho": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/giuliocapecchi/jisho-mcp", "jisho-mcp"]
    }
  }
}
```

Common config locations:

| Client | Config file |
|--------|-------------|
| Claude Desktop | `claude_desktop_config.json` |
| Codex (OpenAI) | `~/.codex/config.json` |
| OpenCode | `opencode.json` |

## Permanent install

If you prefer a system-wide command:

```bash
uv tool install git+https://github.com/giuliocapecchi/jisho-mcp
```

Then run directly:
```bash
jisho-mcp
```

Or add to your MCP config:
```json
{
  "mcpServers": {
    "jisho": {
      "command": "jisho-mcp"
    }
  }
}
```


## Development

```bash
git clone https://github.com/giuliocapecchi/jisho-mcp.git
cd jisho-mcp
uv sync
uv run jisho-mcp
```

## Tools

| Tool | Description |
|------|-------------|
| `search_words(keyword, page=1)` | Search dictionary entries. |
| `get_word(slug)` | Fetch the entry with the exact slug, or `None` if no exact match. |

### Example

`get_word("水")` returns:

```json
{
  "slug": "水",
  "is_common": true,
  "jlpt": ["jlpt-n5"],
  "japanese": [{"word": "水", "reading": "みず"}],
  "senses": [
    {
      "english_definitions": ["water (esp. cool or cold)"],
      "parts_of_speech": ["Noun"],
      "see_also": ["湯 ゆ"]
    },
    {
      "english_definitions": ["fluid (esp. in an animal tissue)", "liquid"],
      "parts_of_speech": ["Noun"]
    }
  ]
}
```

## License

[MIT](LICENSE)