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.

Source material and licensing

The Revenue document, eBrief and tax-treaty tools return material published by the Office of the Revenue Commissioners and reused under Revenue's Public Sector Information Licence (CC BY 4.0):

Information provided courtesy of the Revenue Commissioners under a Creative Commons Attribution 4.0 International (CC BY 4.0) licence

Every such result carries this statement in attribution.source. Document text is extracted from Revenue's original PDFs; descriptions, keywords and groupings are Irish Tax Hub's own. Irish Tax Hub is not affiliated with or endorsed by Revenue.

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

With irishtaxhubapi running locally on its default port 8000, no configuration is needed:

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.

Deployment OIDC

The deploy role and its policy are owned by the account-wide manifest in irishtaxhub-scripts/aws-iam-deploy-roles/ (manifest.json and policies/GitHubActions-irishtaxhub-mcp-Policy.json); change them there and apply with its apply.py. The scripts below are recovery helpers for rebuilding the role from this repository.

GitHub Actions deploys use a repository-specific OIDC subject template containing the claims repo, context, ref. Configure it idempotently with:

gh auth login
./scripts/configure_github_oidc_subject.sh
./scripts/setup_github_oidc.sh

The first script requires gh, jq, and repository administration access. The IAM role accepts only these subjects:

repo:jhurleyai/irishtaxhub-mcp:environment:stage:ref:refs/heads/main
repo:jhurleyai/irishtaxhub-mcp:environment:prod:ref:refs/heads/main

Render the exact trust and permissions documents for review without calling AWS:

POLICY_ACCOUNT_ID_OVERRIDE=123456789012 \
  ./scripts/setup_github_oidc.sh --render-policies /tmp/irishtaxhub-mcp-iam

Role lifecycle and PassRole access are limited to the stage and production Lambda execution roles. PassRole is accepted only when the destination service is Lambda, and the deploy role can attach only AWSLambdaBasicExecutionRole to those roles.

For an existing live role, temporarily allow both the current and new subjects in IAM, run the repository configuration script, then rerun setup_github_oidc.sh to leave only the exact subjects above. Changing either side alone temporarily prevents deployments.

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