voikko-mcp

voikko-mcp


Finnish language verification MCP server powered by libvoikko. 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 and Docker Compose

Quick start

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:

{
  "mcp": {
    "voikko-mcp": {
      "type": "remote",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.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 — Finnish language processing library by the Voikko project
• MCP Python SDK — Model Context Protocol implementation by Anthropic
• FastMCP — High-level MCP server framework
• Finnish morphological dictionary (voikko-fi) maintained by the Voikko community

License

GNU General Public License v3.0 or later — see LICENSE for details.