ahnl/torium

An unofficial Python client for the Finnish Tori.fi marketplace. 🇫🇮 

Browse listings, manage your own listings, and chat with buyers. From the terminal, your Python code, or Claude.

Installation • CLI • MCP Tools • Library

---

Installation

Choose your preferred installation method:

• Hosted remote MCP server. Easiest, just connect claude.ai or ChatGPT to https://torium.fi/mcp.
• Local install (MCP and CLI). Run the MCP server and CLI on your own machine.
• Self-hosted remote MCP server. Host the remote MCP server yourself.

Hosted remote MCP server

The simplest way to use Torium. We host the MCP server at https://torium.fi/mcp. Just add it as a connector in claude.ai and log in with your Tori.fi account.

See torium.fi for setup instructions and a video walkthrough.

Local install (MCP and CLI)

1. Clone and install:

git clone https://github.com/ahnl/torium
uv tool install ./torium

This places torium-mcp (and torium) on your PATH globally.

2. Authenticate (once):

torium auth setup

Opens a browser for OAuth login. On macOS and Linux the redirect is captured automatically (Linux registers a temporary .desktop URL handler via xdg-mime).

On Windows, after login the browser will show an infinite loading spinner or a “can’t open” error. Open the browser’s developer tools (F12) → Console, find the failed redirect URL starting with fi.tori.www..., right-click it to copy the link address, and paste it into the terminal. Do this quickly. The code in the URL expires in 30-60 seconds.

Credentials will be saved to ~/.config/torium/credentials.json. Alternatively, set TORI_REFRESH_TOKEN in your environment. The MCP server will use it directly, no credentials file needed.

3. MCP: Add to Claude Desktop:

Go to Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "torium": {
      "command": "torium-mcp"
    }
  }
}

Restart Claude Desktop. The torium tools are now available.

Updating:

cd torium && git pull && uv tool install --reinstall .

Self-hosted remote MCP server