Get started with INS MCP in 20 minutes

Expected outcome

By the end of this guide, INS 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 official statistics with a source attribution. Estimated total time: 15–20 minutes if Python is already installed; allow about ten extra minutes otherwise.

Prerequisites

• An MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code (Copilot agent mode), Cline/Roo Code, Windsurf, or the MCP Inspector.
• Python 3.10 or later. Download from python.org if not already installed.
• No extra package manager. INS MCP installs with the standard library venv and pip — there is no uv step and no lockfile.
• An internet connection to clone the repository and reach dataportal.ins.tn at query time.

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/ins-tunisia-mcp.git
cd ins-tunisia-mcp
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows (PowerShell):
# .venv\Scripts\Activate.ps1
pip install -e .

pip install -e . resolves and installs every dependency declared in pyproject.toml into the virtualenv. On a fresh checkout this usually takes under a minute.

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

Unlike a global interpreter, the virtualenv's Python is the one that has INS MCP installed — so the client must launch that exact interpreter. Note its absolute path:

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

You will paste this in place of /absolute/path/to/ins-tunisia-mcp/.venv/bin/python in 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 ins; only the file format changes between clients.

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": {
    "ins": {
      "command": "/absolute/path/to/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

Save the file, then restart Claude Desktop.

Cursor, Windsurf, other stdio-MCP clients

Most clients accept the same shape as Claude Desktop. Add the snippet to the client's MCP settings file — Cursor uses .cursor/mcp.json (project) or ~/.cursor/mcp.json (global); Windsurf uses ~/.codeium/windsurf/mcp_config.json — then reload and enable the server in the client's settings:

{
  "mcpServers": {
    "ins": {
      "command": "/absolute/path/to/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

VS Code (Copilot agent mode)

VS Code uses a servers key with an explicit type:

{
  "servers": {
    "ins": {
      "type": "stdio",
      "command": "/absolute/path/to/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

Claude Code (CLI)

A single command, no configuration file:

claude mcp add ins -- /absolute/path/to/ins-tunisia-mcp/.venv/bin/python -m ins_mcp

Step 4 — First test call

In your client, start a new conversation and ask:

"What tools are exposed by the ins server?"

A correct response lists the seven tools: ins_list_sources, ins_search_sources, ins_get_source, ins_get_dimension_elements, ins_get_data, ins_get_availability, and ins_refresh_catalogue. If that list appears, the connection works.

Step 5 — Your first real query

Try a question that exercises the search → drill → fetch chain:

"Show Tunisia's GDP at market prices from 2014 to 2017."

The server resolves the indicator code, fetches the observations, and returns four annual values (80,865.5; 84,689.2; 89,792.2; 96,324.7 million dinars) from the cube "Principaux agrégats", each carrying an attribution block crediting the INS data portal. On the very first call the server seeds a local catalogue (a few seconds); this is one-time.

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. A global interpreter does not have ins_mcp installed.
• "command not found" / spawn error in the client's MCP logs. GUI clients often do not inherit your shell's PATH, so neither python nor the ins-mcp console script is guaranteed to be found. Always use the absolute venv-Python path in the configuration.
• The first call is slow, or has_data looks wrong right after setup. Expected: the catalogue seeds on first use (~2–4 seconds) and a background probe finishes flagging cubes over the next minute or two. No action needed; it self-completes.
• A cube you expect is missing. Ask the assistant to run ins_refresh_catalogue to re-pull the catalogue from the live portal — newly published cubes appear after a refresh.
• A source is listed but every query returns no observations. Check has_data on the source: 10 of the 78 INS cubes (some 2014-census cross-tabs) are published-but-empty shells flagged has_data: false. This is real INS data absence, not a bug. (A date window without a frequency returns a frequency_required error — supply annual or quarterly.)
• You want to verify the server runs before wiring it to a client. From the clone directory, run:

  bash Copier

  npx @modelcontextprotocol/inspector /absolute/path/to/ins-tunisia-mcp/.venv/bin/python -m ins_mcp

  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?

INS MCP runs as a local subprocess your MCP client spawns over stdio; there is no hosted endpoint. The data is public, so the value is the local façade over the portal — no server to operate or secure. This is the standard MCP architecture, the same model as agridata MCP.

Which MCP clients are supported?

Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code (Copilot agent mode), Cline/Roo Code, Windsurf, and the MCP Inspector. The configuration format differs slightly between clients; the launch command is the same.

Why pip and a virtualenv, and not uv?

INS MCP uses a plain Python virtualenv and "pip install -e ." — no extra tooling to install, and it works with any standard Python 3.10 or later. (Its sibling agridata MCP uses uv; INS deliberately keeps the toolchain minimal.)

Is the data freely reusable?

Yes. The data follows the INS conditions d'utilisation (attribution-style, compatible with CC-BY / ODC-BY, commercial use allowed); attribution is mandatory and every response embeds a source-attribution block to reproduce. Note this is the INS conditions d'utilisation — not the LNDPO that governs agridata.

Where do I report a bug or request a dataset?

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