Installation #

The server is part of the metafrasi Python package and runs over stdio, so your MCP client launches it — you never run it by hand.

Requirements #

• Python ≥ 3.10 (tested through 3.14)
• A Microbooks account and a personal access token

Install the package #

pipx install "metafrasi[mcp]"

This installs the metafrasi-mcp executable that MCP clients invoke.

pipx is recommended because your client launches metafrasi-mcp by name and so needs it on PATH; a plain pip install into a virtualenv leaves it where the client cannot find it. pip install "metafrasi[mcp]" works too if you give the client an absolute path to the script instead.

The package is metafrasi. metafrasi-mcp is the command it installs, not a package name — pip install metafrasi-mcp finds nothing. The [mcp] extra is what pulls in the MCP SDK.

Example: Claude Desktop #

The steps are the same in any MCP client; only where the configuration file lives differs. In Claude Desktop, open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "microbooks": {
      "command": "metafrasi-mcp",
      "env": {
        "MICROBOOKS_API_URL": "https://api.microbooks.io",
        "MICROBOOKS_TOKEN": "<personal access token>"
      }
    }
  }
}

One-click setup. Signed-in users can generate this configuration — token included — at Dashboard → Developers → Connect AI assistant on microbooks.io.

Restart the client; the Microbooks tools appear in its tools menu.

Check it works #

Ask the assistant to call get_ledger_setup. It should come back with your entity’s name and reporting currency, the configured currencies, and the reporting periods — one call that confirms the token and the connection together.

Other MCP clients #

Any client that supports stdio servers works the same way, and most accept the same mcpServers JSON shown above: run metafrasi-mcp with the environment variables described in Configuration.