KRA eTIMS MCP Server

A high-performance Model Context Protocol (MCP) server providing complete, authoritative knowledge, API schemas, validation rules, code snippets, and automated error diagnostics for Kenya Revenue Authority (KRA) eTIMS integrations.

Enables AI coding assistants to seamlessly write, validate, and troubleshoot eTIMS integrations across OSCU (Cloud REST), VSCU (Virtual Sales Control Unit), TIS (Trader Invoicing System), Buyer-Initiated Invoicing (BII), Fuel Station Automation, and Stock Management.

Supported AI Assistants

Works out-of-the-box via the standard STDIO transport with:

Related MCP server: eleata e-invoice MCP server

Quickstart (Zero-Install via NPX)

You can run the server directly without cloning or building:

npx -y kra-etims-mcp

Client Setup Instructions

1. Cursor

Add to your project's .cursor/mcp.json (or global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "kra-etims": {
      "command": "npx",
      "args": ["-y", "kra-etims-mcp"]
    }
  }
}

2. Google Antigravity

Add to .agents/mcp_config.json in your workspace root, or configure interactively using the /mcp command:

{
  "mcpServers": {
    "kra-etims": {
      "command": "npx",
      "args": ["-y", "kra-etims-mcp"]
    }
  }
}

3. Zed IDE

Add to .zed/settings.json in your project or global ~/.config/zed/settings.json:

{
  "context_servers": {
    "kra-etims": {
      "command": {
        "path": "npx",
        "args": ["-y", "kra-etims-mcp"]
      }
    }
  }
}

Or when running via local Docker container:

{
  "context_servers": {
    "kra-etims": {
      "command": {
        "path": "docker",
        "args": ["run", "-i", "--rm", "kra-etims-mcp"]
      }
    }
  }
}

4. Claude Code

Run the CLI command:

claude mcp add --transport stdio kra-etims -- npx -y kra-etims-mcp

Or create .mcp.json in your repository root:

{
  "mcpServers": {
    "kra-etims": {
      "command": "npx",
      "args": ["-y", "kra-etims-mcp"]
    }
  }
}

5. OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.kra-etims]
command = "npx"
args = ["-y", "kra-etims-mcp"]

6. GitHub Copilot (VS Code)

Add to .vscode/mcp.json:

{
  "mcpServers": {
    "kra-etims": {
      "command": "npx",
      "args": ["-y", "kra-etims-mcp"]
    }
  }
}

Running in Docker (Automatic Reboot Restart)

The server can run as a background container configured with restart: unless-stopped, so it stays alive across host reboots.

Option A: Docker Compose (Recommended)

1. Start the service:

docker compose up -d

2. Check health status:

curl http://localhost:3000/health

3. Connect your IDEs using the HTTP/SSE endpoint:

• SSE Stream: http://localhost:3000/sse

• Messages: http://localhost:3000/message

Option B: Docker CLI

Run in daemon mode with automatic reboot restart:

docker run -d \
  --name kra-etims-mcp \
  --restart unless-stopped \
  -p 3000:3000 \
  kra-etims-mcp --http 3000

Run in STDIO mode directly from your IDE:

docker run -i --rm kra-etims-mcp

OS-Specific Startup & Setup Guide (Linux, macOS, Windows)

Whether you choose Docker or Node.js (npx), follow the instructions below tailored to your operating system.

Linux (Ubuntu, Debian, Fedora, Arch, CentOS)

Method 1: Docker (Single Command with Reboot Auto-Restart)

1. Ensure Docker is running:

   sudo systemctl enable --now docker

2. Start the container:

   docker compose up -d

   (Or with pure Docker CLI):

   docker run -d --name kra-etims-mcp --restart unless-stopped -p 3000:3000 kra-etims-mcp --http 3000

3. Verify running status:

   curl http://localhost:3000/health

Method 2: Node.js / NPX (No Docker Required)

Requires Node.js 18+ installed (node -v):

npx -y kra-etims-mcp

Linux Client Configuration File Paths:

• Cursor: ~/.cursor/mcp.json or project .cursor/mcp.json

• Google Antigravity: ~/.gemini/config/mcp_config.json or project .agents/mcp_config.json

• Zed IDE: ~/.config/zed/settings.json or project .zed/settings.json

• Claude Code: ~/.claude.json or project .mcp.json

• OpenAI Codex: ~/.codex/config.toml

• GitHub Copilot / VS Code: ~/.config/Code/User/globalStorage/github.copilot/mcp.json or project .vscode/mcp.json

macOS (Apple Silicon M1/M2/M3/M4 & Intel)

Method 1: Docker (Docker Desktop or OrbStack)

1. Ensure Docker Desktop is open: Launch Docker.app or OrbStack.app from Applications.

2. Start the container: In Terminal (zsh):

   docker compose up -d

   (Or with pure Docker CLI):

   docker run -d --name kra-etims-mcp --restart unless-stopped -p 3000:3000 kra-etims-mcp --http 3000

3. Verify running status:

   curl http://localhost:3000/health

Method 2: Node.js / NPX (No Docker Required)

Requires Node.js installed (brew install node):

npx -y kra-etims-mcp

macOS Client Configuration File Paths:

• Cursor: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json or project .cursor/mcp.json

• Google Antigravity: ~/.gemini/config/mcp_config.json or project .agents/mcp_config.json

• Zed IDE: ~/Library/Application Support/Zed/settings.json or project .zed/settings.json

• Claude Code: ~/.claude.json or project .mcp.json

• OpenAI Codex: ~/.codex/config.toml

• GitHub Copilot / VS Code: ~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json or project .vscode/mcp.json

Windows (10 & 11)

Method 1: Docker Desktop (with WSL2 Backend)

1. Ensure Docker Desktop is running: Start Docker Desktop from the Start Menu. Ensure WSL2 integration is enabled.

2. Start the container (Run in PowerShell or Command Prompt):

   docker compose up -d

   (Or with pure Docker CLI):

   docker run -d --name kra-etims-mcp --restart unless-stopped -p 3000:3000 kra-etims-mcp --http 3000

3. Verify running status:

   curl http://localhost:3000/health
   # or in PowerShell:
   Invoke-RestMethod http://localhost:3000/health

Method 2: Node.js / NPX on Windows

Requires Node.js installed from nodejs.org:

npx -y kra-etims-mcp

{
  "mcpServers": {
    "kra-etims": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "-y", "kra-etims-mcp"]
    }
  }
}

{
  "mcpServers": {
    "kra-etims": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "kra-etims-mcp"]
    }
  }
}

Windows Client Configuration File Paths:

• Cursor: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json or project .cursor\mcp.json

• Google Antigravity: %USERPROFILE%\.gemini\config\mcp_config.json or project .agents\mcp_config.json

• Zed IDE: %APPDATA%\Zed\settings.json or project .zed\settings.json

• Claude Code: %USERPROFILE%\.claude.json or project .mcp.json

• OpenAI Codex: %USERPROFILE%\.codex\config.toml

• GitHub Copilot / VS Code: %APPDATA%\Code\User\globalStorage\github.copilot\mcp.json or project .vscode\mcp.json

Capabilities & Developer Tools

1. Tools

2. Resources (etims://...)

Directly attachable knowledge documents:

• etims://docs/oscu-vs-vscu — OSCU vs VSCU Architecture & Integration Guide

• etims://docs/onboarding-guide — Step-by-step Onboarding & Handshake Guide

• etims://docs/credit-notes-rules — Credit Notes & Invoice Reversal Rules

• etims://docs/buyer-initiated-invoicing — Buyer-Initiated Invoicing (BII) & Reverse Invoicing

• etims://docs/stock-management — Mandatory Stock Management Guide

• etims://docs/fuel-station-system — Forecourt Automation & Fuel Station System

• etims://docs/tis-qr-code-spec — TIS Receipt Layout & QR Code Formula

• etims://codes/all — All system code tables dictionary

• etims://errors/all — All error codes and troubleshooting catalog

• etims://api/catalog — Complete API endpoints catalog

3. Guided Prompts

• scaffold-etims-client — Scaffolds an eTIMS API client in TypeScript, Python, PHP, or Go.

• debug-etims-error — Interactive troubleshooting for failed KRA requests.

• implement-credit-note — Step-by-step credit note generation sequence.

• setup-stock-sync — Workflow for mandatory stock synchronization.

Performance & Architecture

• Sub-2ms Execution: In-memory pre-compiled index powered by MiniSearch.

• Zero Disk Overhead: Static assets and code tables are bundled at build time; no database or external network calls needed during knowledge queries.

• Safe Stdio Transport: All diagnostic logging writes strictly to stderr, ensuring the JSON-RPC 2.0 communication channel on stdout remains uncorrupted.

Development & Testing

1. Install dependencies:

   npm install

2. Build project:

   npm run build

3. Run automated tests:

   npm test

4. Type checking:

   npm run typecheck

License

MIT © 2026 KRA eTIMS Open Source Community