Taxcode

What taxcode does

The taxcode MCP server provides reference data and deterministic checks for US tax-law research. Its catalog covers the Internal Revenue Code and related federal regulations, Puerto Rico laws and administrative circulars, and statutory definitions or computations for all 50 states plus the District of Columbia. The available material includes residency rules, capital-gains sourcing, no-income-tax jurisdictions, flat-tax systems, graduated rates, convenience-of-the-employer rules, and selected local taxes.

The server belongs in the ⚖️ Legal category, but it is not a tax or legal advice system. Its summaries, translations, heuristic checks, and computational outputs are unofficial and intended for information or research. Enacted statutory and administrative sources in their official language control.

How it works

A FastMCP gateway exposes mounted system, statutes, and compliance sub-servers over standard stdio or streamable HTTP transports. The statutes tools query an in-memory or file-backed DuckDB engine containing 106 statutes and 12 publications. Queries support full-text search, point-in-time lookup, tax-year selection, and filtering for superseded provisions.

Compliance tools run deterministic models against the catalog. Puerto Rico bona-fide residency checks consider presence-day tests, tax home, and closer-connection factors. The built-in-gain model allocates Section 937 or Act 60 capital gains between pre-move and post-move holding periods. State residency evaluation covers presence days, permanent place of abode, domicile risk indicators, and tax liability across 51 jurisdictions.

Setup and configuration

Stdio is the default transport and does not require an authentication token. The repository provides a taxcode-mcp console command, and a local clone can be run with uv run --directory; installing the project with uv tool install . or pip install . also places the server commands on PATH.

For streamable HTTP, use TAXCODE_MCP_AUTH_TOKEN when serving beyond localhost. Authenticated requests must include a bearer token. The server refuses a non-loopback bind without a token unless TAXCODE_MCP_ALLOW_UNAUTHENTICATED_BIND is enabled. HTTP sessions expire after 30 minutes by default, with the timeout configurable through FastMCP settings.

Profiles include full, system, statutes, compliance, readonly, researcher, and advisor. TAXCODE_MCP_ENABLE_TOOL_SEARCH can replace the flat tool catalog with dynamic search meta-tools, while code mode is an experimental option requiring its extra dependency.

Tools and capabilities

The taxcode MCP server exposes eight read-only tools:

• system_get_health_status reports server health.
• statutes_lookup_statute retrieves a statute or provision.
• statutes_search_tax_code performs tax-code search.
• statutes_list_publications lists available publications.
• compliance_evaluate_pr_bona_fide_residency evaluates Puerto Rico residency factors.
• compliance_calculate_built_in_gain_sourcing calculates holding-period sourcing.
• compliance_evaluate_georgia_residency evaluates Georgia residency.
• compliance_evaluate_state_residency evaluates residency across US state jurisdictions.

Profiles can limit exposure by domain or use case. The researcher profile focuses on statutes and circulars, while advisor focuses on cross-border residency and built-in-gain calculations. Read-only MCP annotations are applied to the tools.

Limitations and notes

Outputs are not formal tax opinions, legal advice, audit representation, or authoritative translations. The documentation identifies the statutory catalog as a reference source, so users should verify conclusions against current official materials. Historical results depend on the requested tax year and available statutory versions. HTTP deployments also require deliberate host and authentication configuration to avoid unauthenticated access.