Compass MCP Server

A small, self-contained MCP server that lets Claude run SQL queries against Infor Compass (Data Fabric) directly from chat. You ask a question, Claude writes the SQL, fires it through this server, and reads back the results — including automatically exporting large result sets to Excel when they're too big to show in chat.

It wraps the Compass async query API (submit → poll → fetch) and handles Infor ION API OAuth2 authentication automatically using your own .ionapi credentials file — nothing Compass-related is hardcoded, so anyone with access to their own Infor tenant can use this as-is.

Prerequisites

• Python 3.10+ — python.org/downloads (Windows: tick "Add Python to PATH" during install)

• Claude Desktop

• One or two .ionapi credentials files from your Infor tenant:

  • credentials.ionapi — for production (required)

  • credentials_trn.ionapi — for training environment (optional)

  Get these from your Infor ION API administrator, or generate them yourself: Infor OS Portal → API Gateway → Authorized Apps → create/select an app → Download credentials. It downloads as a .ionapi file. If you need access to both environments, you'll need separate credentials for each.

Related MCP server: MCP Database Server

Quick start

1. Download this repo — click the green Code button above → Download ZIP — and unzip it anywhere (e.g. Desktop or Downloads).

2. Drop your credentials file(s) into the unzipped folder:

   • Rename your production credentials to credentials.ionapi (required)

   • (Optional) Rename a training credentials file to credentials_trn.ionapi if you have access to a training environment

3. Run the installer:

   • macOS: double-click install.command

   • Windows: double-click install.bat

   This copies the folder to your home directory, builds an isolated Python environment, verifies it can connect to Compass, and registers the server with Claude Desktop — all in one pass.

4. Fully quit and reopen Claude Desktop (not just close the window — quit it completely so it reloads its MCP server list).

5. (Optional but recommended) Set up a Claude Project to manage environment selection:

   • Create a new Claude Project

   • Add the contents of claude_project_instructions.md to your Project Instructions

   • This enables Claude to ask which environment you want at the start of each conversation

6. Try it in a chat:

   "Ping Compass to make sure it's connected."

   "Query Compass: select the first 10 rows from <your table>."

Windows SmartScreen note: the first time you run install.bat, Windows may show a blue "Windows protected your PC" warning, because it's a script downloaded from the internet. Click More info → Run anyway. This is standard for any unsigned script and not a sign anything is wrong.

Tools exposed to Claude

This server exposes tools for two environments: Production and Training (TRN). Each environment has its own set of tools:

Production Environment

• query_compass(sql, max_rows=1000) — run a SQL query against production, return columns and rows (plus row_count, truncated, query_id). Failed queries return a clear error + message.

• export_compass_to_excel(sql, filename="compass_export", rows_per_file=500000) — run a SQL query in full and stream every row straight into one or more .xlsx files in your Downloads folder, instead of returning rows in chat. Streams to disk page-by-page (never holding the full result in memory) and auto-splits into _part1.xlsx, _part2.xlsx, etc. once a result exceeds the rows-per-file setting — this is what makes multi-hundred-thousand-row exports practical.

• ping_compass() — check production Compass connectivity/auth. Returns {"ok": true, "response": "pong"} when healthy.

Training (TRN) Environment

• query_compass_trn(sql, max_rows=1000) — same as query_compass but against training

• export_compass_to_excel_trn(sql, filename="compass_export", rows_per_file=500000) — same as export_compass_to_excel but against training

• ping_compass_trn() — check training Compass connectivity/auth

Using this in a Claude Project

Several files are included to enhance Claude's Compass query capabilities:

Environment Management

• claude_project_instructions.md — Recommended: Add this file's contents to your Claude Project's Project Instructions to enable seamless environment selection. Claude will ask which environment (Production or Training) you want to use at the start of each conversation, then automatically use the corresponding tools throughout the session. See the file for full instructions.

Query Optimization (Optional)

• SX_Dictionary_AI_v3.md — a business-term-to-table/field reference covering 64 core CSD tables (customers, orders, inventory, pricing, AP/AR, warehouse management, etc.), generated from Infor's CSD data-conversion field maps. Add it as a Project Knowledge file.

• compass-query-agent-instructions.md — a starting-point Project Instructions template: tells Claude to default to writing/running SQL rather than asking clarifying questions, lists always-on filters (cono, statustype), and maps plain-language requests ("customers", "orders", "inventory") to the right tables. Fill in the bracketed placeholders (your company name, your warehouse code list) before using it — the rest is generic to any CSD/SX.e install.

The environment management file is recommended. The query optimization files are optional but recommended context for a Claude Project built around Compass.

What's in this folder

Manual setup

If you'd rather not run the one-click installer, you can do it by hand:

1. Clone or download this repo, and place your .ionapi file inside it as credentials.ionapi.

2. Build the environment:

   macOS / Linux:

   cd compass-mcp
   bash setup.sh

   Windows:

   cd compass-mcp
   setup.bat

   This creates a .venv, installs dependencies, and runs a live self-test that authenticates and pings Compass. You should see:

   { "ok": true, "status_code": 200, "response": "pong" }

3. Note the Python interpreter path it prints at the end, e.g. /path/to/compass-mcp/.venv/bin/python.

4. Open the Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Windows, Microsoft Store build of Claude Desktop: the Store version is sandboxed and never sees %APPDATA%\Claude — its config instead lives at %LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\claude_desktop_config.json (the <hash> suffix is publisher-specific; there's normally only one Claude_* folder under Packages). _register_claude.py (used by the installers) already detects this automatically.

   (In Claude Desktop you can also reach it via Settings → Developer → Edit Config.)

5. Add a compass entry (merge into existing mcpServers if present), substituting your actual folder path:

   macOS / Linux:

   {
     "mcpServers": {
       "compass": {
         "command": "/path/to/compass-mcp/.venv/bin/python",
         "args": ["/path/to/compass-mcp/server.py"]
       }
     }
   }

   Windows (note Scripts\python.exe and double backslashes):

   {
     "mcpServers": {
       "compass": {
         "command": "C:\\Users\\you\\compass-mcp\\.venv\\Scripts\\python.exe",
         "args": ["C:\\Users\\you\\compass-mcp\\server.py"]
       }
     }
   }

6. Fully quit and reopen Claude Desktop.

Updating an existing install

To pick up a newer version of this tool (e.g. a new release from this repo), just replace server.py, compass_client.py, exporter.py, and excel_writer.py in your installed folder with the latest versions, then fully quit and reopen Claude Desktop. Since the server is already registered, you don't need to touch claude_desktop_config.json or re-run the installer — that step only happens once, the first time.

Moving to another computer

The whole folder is self-contained. To move it:

1. Copy the folder (the .venv does not transfer — it has machine-specific paths; leave it behind or delete it). This works across operating systems.

2. On the new machine, rebuild the venv: bash setup.sh (macOS/Linux) or setup.bat (Windows).

3. Update the paths in the Claude Desktop config to match the new location and OS (see the Windows path format above).

credentials.ionapi travels with the folder, so there's no re-entering secrets — just make sure you're not copying it somewhere less secure than where it started.

How it works

1. Auth — reads credentials.ionapi, performs an OAuth2 password grant against the ION token endpoint (pu + ot), caches the bearer token and refreshes it ~60s before expiry.

2. Submit — POST {base}/jobs/ with the SQL as a plain-text body → returns a queryId.

3. Poll — GET {base}/jobs/{queryId}/status/ every 2s. Compass returns HTTP 202 while RUNNING and 201 when FINISHED.

4. Fetch — GET {base}/jobs/{queryId}/result/ → rows. The server normalizes them into columns + rows.

The Compass base URL is derived from your .ionapi tenant automatically — there's nothing tenant-specific to configure.

Configuration overrides (optional)

All optional — see .env.example. Set them as environment variables in the Claude config's env block if needed, e.g. a longer timeout for big queries:

"compass": {
  "command": "/path/to/compass-mcp/.venv/bin/python",
  "args": ["/path/to/compass-mcp/server.py"],
  "env": { "COMPASS_POLL_TIMEOUT": "300", "COMPASS_MAX_ROWS": "5000" }
}

Security

• credentials.ionapi contains live secrets for your Infor tenant. Never commit it to git or share it outside your organization. The included .gitignore keeps it (and any other *.ionapi file) out of version control.

• Each person should use their own .ionapi file, scoped to whatever permissions their Infor admin has granted them — don't pass credentials files around between teammates.

• The installers back up your existing claude_desktop_config.json (as claude_desktop_config.json.bak) before modifying it, so a merge issue is always recoverable.

Troubleshooting

License

MIT