Irish Tax Hub MCP server

FastMCP server exposing a curated, read-only toolset backed by the Irish Tax Hub API.

Hosted endpoints

• Production: https://mcp-prod.aws.irishtaxhub.ie/mcp

• Stage: https://mcp-stage.aws.irishtaxhub.ie/mcp

The hosted service uses stateless Streamable HTTP. For local MCP clients, run the same server over standard input/output as described below.

Related MCP server: OpenAPI MCP Server

Tools

Tools are deliberately curated rather than generated dynamically. The OpenAPI document is used to validate calculator requests, while stable tool names and descriptions form the MCP interface.

Install

Python 3.11 and Poetry are recommended:

poetry install

An editable pip installation also works:

pip install -e .

Configure

The server reads these environment variables:

For production-backed local use:

export IRISHTAXHUB_BASE_URL="https://prod.aws.irishtaxhub.ie"
export IRISHTAXHUB_OPENAPI="https://prod.aws.irishtaxhub.ie/openapi.json"
poetry run irishtaxhub-mcp

For a locally running API, set the base URL explicitly — the built-in default is http://localhost:5000, but irishtaxhubapi serves on port 8000:

export IRISHTAXHUB_BASE_URL="http://127.0.0.1:8000"
poetry run irishtaxhub-mcp

You can also run the module or FastMCP entrypoint directly:

python -m irishtaxhub_mcp.server
fastmcp run src/irishtaxhub_mcp/server.py

MCP client configuration

Example local standard-input/output configuration:

{
  "mcpServers": {
    "irishtaxhub": {
      "command": "poetry",
      "args": ["run", "irishtaxhub-mcp"],
      "cwd": "/absolute/path/to/irishtaxhub-mcp",
      "env": {
        "IRISHTAXHUB_BASE_URL": "https://prod.aws.irishtaxhub.ie",
        "IRISHTAXHUB_OPENAPI": "https://prod.aws.irishtaxhub.ie/openapi.json"
      }
    }
  }
}

Restart the client after changing its MCP configuration.

Examples

Discover the available calculators, inspect the selected input schema, and then calculate:

{"tool": "list_calculators", "arguments": {}}

{
  "tool": "get_calculator_schema",
  "arguments": {"calculator_name": "refund"}
}

{
  "tool": "calculate_tax",
  "arguments": {
    "calculator_name": "refund",
    "inputs": {
      "marital_status": "single",
      "year": 2025,
      "employment_income": {"income": 50000, "tax_paid": 18000}
    }
  }
}

Search the Revenue and treaty corpora:

{"tool": "search_revenue_documents", "arguments": {"query": "principal private residence"}}

{"tool": "search_tax_treaties", "arguments": {"query": "employment income", "country": "France"}}

Development

poetry run black --check .
poetry run isort --check-only .
poetry run flake8 .
poetry run pytest

The implementation calls the deployed HTTP API rather than importing API internals, keeping this service small and independently deployable. src/irishtaxhub_mcp/asgi.py provides the ASGI entrypoint used by the Lambda Web Adapter deployment.

Claude PR review

.github/workflows/claude-pr-review.yml can review pull requests when the repository has a valid CLAUDE_CODE_OAUTH_TOKEN secret. Generate a replacement with claude setup-token when required, then update it with:

gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo jhurleyai/irishtaxhub-mcp