Content
# voikko-mcp
[](LICENSE)
Finnish language verification MCP server powered by [libvoikko](https://voikko.puimula.org/). Provides spell checking, grammar checking, morphological analysis, hyphenation, and tokenization as MCP tools for any MCP-compatible client (OpenWebUI, OpenCode, Claude Desktop, Cursor, etc.).
## Features
- **Spell checking** — verify single words against libvoikko's Finnish dictionary
- **Grammar checking** — detect capitalization, word-order, and agreement errors
- **Morphological analysis** — inspect base form, case, number, possessive suffixes
- **Hyphenation** — syllable-aware word splitting for line-breaking and pronunciation
- **Tokenization** — split Finnish text into words, whitespace, and punctuation tokens
- **Streamable HTTP transport** — runs as a web server, no local process management needed
## Prerequisites
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
## Quick start
```bash
docker compose up --build
```
The server starts on `http://localhost:8000` with Streamable HTTP transport (endpoint at `/mcp`).
## Tools
| Tool | Parameters | Returns |
|------|------------|---------|
| `check_spelling` | `word: str` | `{word, correct, suggestions}` |
| `suggest_spelling` | `word: str` | `list[str]` — suggested corrections |
| `check_grammar` | `text: str` | `list[{start, length, snippet, description, suggestions}]` |
| `verify_text` | `text: str` | `{text, is_correct, spelling_errors, grammar_errors}` |
| `analyze_word` | `word: str` | `list[{BASEFORM, CLASS, SIJAMUOTO, ...}]` |
| `hyphenate_word` | `word: str` | `{word, hyphenated}` |
| `tokenize_text` | `text: str` | `list[{token_type, token_text, position}]` |
All tools include error handling and return empty/fallback values on failure.
## Client configuration
### OpenWebUI
**Settings > MCP Servers > Add**:
- **Name**: `voikko-mcp`
- **Transport**: Streamable HTTP
- **URL**: `http://localhost:8000/mcp`
### OpenCode
Add to `opencode.json`:
```json
{
"mcp": {
"voikko-mcp": {
"type": "remote",
"url": "http://localhost:8000/mcp"
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"voikko-mcp": {
"type": "streamableHttp",
"url": "http://localhost:8000/mcp"
}
}
}
```
### Cursor
Add an MCP server entry with Streamable HTTP transport pointing to `http://localhost:8000/mcp`.
## Architecture
```
Client (OpenWebUI / OpenCode / Claude) ──POST /mcp──▶ uvicorn ──▶ FastMCP ──▶ libvoikko
◀──Streamable HTTP (JSON-RPC)──
```
- **Python 3.11** with **FastMCP** from the official MCP Python SDK
- **libvoikko** C++ library via its Python bindings for all linguistic operations
- **Streamable HTTP transport** over uvicorn, binding `0.0.0.0:8000`
- Docker image based on `python:3.11-slim` with `libvoikko-dev` and `voikko-fi`
## Credits
- [libvoikko](https://voikko.puimula.org/) — Finnish language processing library by the Voikko project
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol implementation by Anthropic
- [FastMCP](https://github.com/jlowin/fastmcp) — High-level MCP server framework
- Finnish morphological dictionary ([voikko-fi](https://github.com/voikko/corevoikko)) maintained by the Voikko community
## License
GNU General Public License v3.0 or later — see [LICENSE](LICENSE) for details.
