mcp-ruoka

Unofficial MCP server for searching Finnish grocery and alcohol products across K-Ruoka, S-Kaupat, and Alko.

• K-Ruoka — Playwright browser with stealth plugin (Cloudflare Turnstile bypass)
• S-Kaupat — Direct HTTP with persisted GraphQL query hashes (extracted via Playwright)
• Alko — Direct HTTP with NextAuth guest session (no browser needed)

Tools

• search_products — Search products by query. Supports all three chains. storeId required for K-Ruoka/S-Kaupat, optional for Alko (national catalog).
• get_stores — List stores, optionally filtered by city and/or chain.

Install as Claude Code plugin

Requires Bun installed.

/plugin marketplace add p18a/mcp-ruoka
/plugin install ruoka@ruoka

Dependencies and Playwright browser are installed automatically on first load.

Deploy to Fly.io

# Clone and enter the repo
git clone https://github.com/p18a/mcp-ruoka.git
cd mcp-ruoka

# Create fly.toml from example (pick your own app name)
cp fly.example.toml fly.toml
fly launch --no-deploy

# Set OAuth credentials
fly secrets set \
  OAUTH_CLIENT_ID=$(openssl rand -hex 32) \
  OAUTH_CLIENT_SECRET=$(openssl rand -hex 32)

# Deploy
fly deploy

Note the client ID and secret — you’ll need them to connect.

Connect via stdio

Runs the server as a subprocess — simplest option for local use.

git clone https://github.com/p18a/mcp-ruoka.git
cd mcp-ruoka
bun install

Then add to your MCP client config:

{
  "mcpServers": {
    "ruoka": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-ruoka/src/index.ts", "--stdio"]
    }
  }
}

Connect via Streamable HTTP

For remote deployments. Deploy first (see above), then point your MCP client at it:

{
  "mcpServers": {
    "ruoka": {
      "type": "streamable-http",
      "url": "https://.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

For direct bearer token auth, set MCP_AUTH_TOKEN as a Fly secret and use it in the header above. For OAuth, configure OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET on both the server and your MCP client.

Local development

bun install
cp .env.example .env
bun run dev

The server runs on http://localhost:3001/mcp by default (Streamable HTTP). Pass --stdio for stdio transport.

Environment variables

Usage examples