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.