Get started with ONEM MCP in 20 minutes

Expected outcome

By the end of this guide, ONEM MCP will be running on your machine, your usual MCP client will be configured to call it, and you will have run a first query that returns Tunisian energy figures with their qualifiers and source provenance. Estimated total time: 15–20 minutes if Python is already installed; allow more if a runtime must be installed first. No data build is needed — the database ships with the repository.

Prerequisites

• An MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, or the MCP Inspector.
• Python 3.12 or later. Download from python.org if not already installed.
• No extra package manager and no system dependencies. ONEM MCP installs two pip wheels (duckdb, mcp); DuckDB needs no server.
• No internet connection at query time. The bundled database is read locally; the network is only needed once, to clone the repository.

Step 1 — Clone, create a virtualenv, and install

Pick a directory where you want the server to live and run:

git clone https://github.com/tanitdata/onem-tunisia-mcp.git
cd onem-tunisia-mcp
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows (PowerShell):
# .venv\Scripts\Activate.ps1
pip install duckdb mcp

That installs the two runtime dependencies into the virtualenv. There is no build step: the extracted energy database (energy.duckdb) ships with the repository, so the server works immediately.

Step 2 — Note the absolute path to the venv's Python

The virtualenv's Python is the one that has duckdb and mcp installed, so the client must launch that exact interpreter. Note its absolute path:

• macOS / Linux: /absolute/path/to/onem-tunisia-mcp/.venv/bin/python
• Windows: C:\absolute\path\to\onem-tunisia-mcp\.venv\Scripts\python.exe

You will paste this, plus the absolute path to mcp_server.py, into the snippets below. Using a bare python is the single most common cause of a failed connection — see Troubleshooting.

Step 3 — Configure your MCP client

Pick the snippet for your client. The server registers under the key onem-energy (note: not the repository name). The PYTHONIOENCODING=utf-8 entry is required — the data carries accented French labels.

Claude Desktop

Configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "onem-energy": {
      "command": "/absolute/path/to/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Save the file, then restart Claude Desktop.

Cursor, other stdio-MCP clients

Most clients accept the same shape as Claude Desktop:

{
  "mcpServers": {
    "onem-energy": {
      "command": "/absolute/path/to/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

VS Code

VS Code uses a servers key with an explicit type:

{
  "servers": {
    "onem-energy": {
      "type": "stdio",
      "command": "/absolute/path/to/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Claude Code (CLI)

A single command, no configuration file:

claude mcp add onem-energy --env PYTHONIOENCODING=utf-8 -- /absolute/path/to/onem-tunisia-mcp/.venv/bin/python /absolute/path/to/onem-tunisia-mcp/mcp_server.py

Step 4 — First test call

In your client, start a new conversation and ask:

"What tools does the onem-energy server expose?"

A correct response lists the twelve tools — among them search_series, get_series, get_observation, compare, get_conflicts, convert_units, and get_scope_glossary. If that list appears, the connection works.

Step 5 — Your first real query

Try a question that exercises the qualifier-aware retrieval:

"Tunisia's natural gas production, PCI basis, annual, 2024."

The server returns the series with calorific_basis: PCI and period_type: annual explicit, alongside cell-level provenance (source edition, page, table, cell) — with no PCI/PCS conflation. Asking it to compare a PCI series against a PCS one returns refused_incompatible: the guardrail, by design.

Troubleshooting

• The client reports the server cannot be found / fails to start. The command must be the absolute path to the virtualenv's Python (…/.venv/bin/python, or …\.venv\Scripts\python.exe on Windows), not a bare python.
• ModuleNotFoundError: duckdb (or mcp) in the client logs. The client launched a different Python than the one where you installed the dependencies. Point the config at the venv interpreter's absolute path.
• Garbled accents or a UnicodeEncodeError on Windows. Add "env": { "PYTHONIOENCODING": "utf-8" } to the server config (it's in the snippets above). The data uses accented French labels.
• A query returns "out-of-scope". Not a bug — some families (prices, trade volumes, refining, exploration) and editions are deferred and reported as out-of-scope by design, distinct from "no data exists".
• compare returns refused_incompatible. Expected guardrail: you tried to relate incompatible series (PCI vs PCS, annual vs year-to-date). Fetch each series separately, or compare compatible ones.
• You want to verify the server runs before wiring it to a client. From the clone directory, run:

  bash Copier

  PYTHONIOENCODING=utf-8 npx @modelcontextprotocol/inspector /absolute/path/to/onem-tunisia-mcp/.venv/bin/python /absolute/path/to/onem-tunisia-mcp/mcp_server.py

  The MCP Inspector opens in your browser and lets you call tools without an LLM client.

What's next

Once the server is running on the client side, browse the research index for more advanced use cases. To share feedback, file a bug, or propose a collaboration, the GitHub repository and the Get Involved page are the entry points.

Frequently asked questions

Why does the server run locally rather than on a hosted endpoint?

ONEM MCP runs as a local subprocess your MCP client spawns over stdio; there is no hosted endpoint. It reads a bundled database, so there is no network connection at query time at all — the same self-hosted model as agridata MCP and INS MCP.

Which MCP clients are supported?

Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, and the MCP Inspector. The configuration format differs slightly between clients; the launch command is the same.

Why does the config set PYTHONIOENCODING=utf-8?

The data carries accented French labels (énergie, redevance, …). On Windows especially, Python may default to a non-UTF-8 console encoding and crash on those characters. Setting PYTHONIOENCODING=utf-8 in the client config avoids it. It is harmless on macOS/Linux, so keep it everywhere.

Is the data freely reusable?

The software is MIT-licensed. The figures are ONEM's, restructured for machine access; the project is unofficial and gives attribution. The exact reuse terms are ONEM's own — consult ONEM for reuse beyond attribution.

Where do I report a bug or request a dataset?

Open an issue on https://github.com/tanitdata/onem-tunisia-mcp or write to contact@tanitdata.org.