# Finnish Foreign Trade (Tulli) MCP

**Query Finland's import and export statistics with your AI agent.** Trade by commodity,
country, and period — from Finnish Customs (Tulli), delivered as clean, ready-to-read rows.
Ask a question in natural language; the server finds the right trade table, figures out its
dimensions, and returns the numbers.

> Example: *"How much did Finland import in total each month last year?"* → the agent
> searches Tulli's trade tables and returns the monthly totals in EUR.

This package is a lightweight, open **bridge** that connects any MCP client (Claude Desktop,
etc.) to the hosted, maintained Finnish Foreign Trade MCP server on Apify. The bridge holds
no data logic — it forwards your requests to the hosted service, which does the real work
(trade queries + json-stat decoding) and meters usage to your own Apify account.

## Tools

| Tool | What it does |
|------|--------------|
| `search_trade_tables` | List Tulli trade tables (CN goods, SITC, NACE industry, BEC). |
| `get_trade_dimensions` | A table's dimensions + classification value codes. |
| `get_trade_data` | Flattened import/export rows by commodity, country and period. |

## Setup

### 1. Get access + an Apify API token

This bridge calls a **hosted, paid Actor** on Apify. You need your own Apify account and
API token:

1. Open the Actor on the Apify Store: **https://apify.com/nectia/finnish-foreign-trade-mcp**
2. Subscribe / rent the Actor (billed per call — pay only for what you use).
3. Copy your token from **Apify Console → Settings → Integrations → API token**.

### 2. Add it to your MCP client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tulli": {
      "command": "npx",
      "args": ["-y", "finnish-trade-mcp-server"],
      "env": {
        "APIFY_API_TOKEN": "PASTE_YOUR_APIFY_TOKEN_HERE"
      }
    }
  }
}
```

Restart your client. No build step, no other keys.

## How it works

```
Your MCP client  ──stdio──►  finnish-trade-mcp-server (this bridge)  ──HTTPS──►  Hosted Actor on Apify  ──►  Tulli/Uljas API
```

The bridge authenticates to the hosted Actor with your `APIFY_API_TOKEN` and transparently
proxies the tools. Your token stays on your machine; Apify meters the calls to your account.

## Data & attribution

Data © Finnish Customs, Uljas statistical database, licensed CC BY 4.0. This project is not
affiliated with or endorsed by Finnish Customs.

## License

MIT © Nectia Automation. The bridge code is open source; the hosted Actor is a commercial
service.