Skip to main content

API & MCP Server

A free JSON API for AI assistants, agents and scripts, also available as an MCP server. It runs the same calculation as this site and needs no API key.

JSON API

Three GET endpoints return JSON, described below. Lists are comma-separated: exempt_taxes takes scope:tax pairs such as federal:social_security,city:city_income, and tax_types takes plain keys.

An OpenAPI 3.1 description of all three is at /openapi.json. Import it into a ChatGPT custom GPT as an Action, or into any agent framework that reads OpenAPI, to get typed tools without MCP.

https://income-tax.org/openapi.json

calculate

Take-home pay and every federal, state and local tax for an annual gross income, with per-paycheck figures, taxable income and the marginal rate. links.tax_tables in the response is the URL of the static tax tables for the same location, ready to fetch.

GET https://income-tax.org/api/calculate?income=120000&state=new_york&city=new_york_city

Try this example

incomerequired · number
Annual gross income in dollars.
staterequired · one of 51 values, e.g. alabama, alaska
US state, or district_of_columbia, in snake_case, e.g. new_york. States without an income tax (texas, florida, ...) are valid.
cityoptional · string
Optional city or county with its own local taxes, in snake_case, e.g. new_york_city. Omit for state-level taxes only. An unknown city returns the list of valid ones for the state.
yearoptional · 2023 | 2024 | 2025 | 2026
Tax year. Defaults to the latest available, 2026.
filing_statusoptional · single | married | married_separately | head_of_household · default "single"
Federal and state filing status.
retirement_contributionoptional · number · default 0
Annual pre-tax 401(k) / traditional IRA contribution in dollars. Reduces income tax but not FICA or other payroll taxes, and is subtracted from take-home. Capped at the year's 401(k) limit.
federal_deductionsoptional · number
Total federal deductions in dollars (itemized, or any custom figure). Omit to use the standard deduction for the filing status.
state_deductionsoptional · number
Total state deductions in dollars. Omit to use the state's own standard deduction, including states that phase it out with income.
exempt_taxesoptional · list of object · default []
Taxes the filer is exempt from, e.g. [{ tax: 'social_security', scope: 'federal' }]. An unknown key returns the list of valid keys for the location.
pay_frequencyoptional · weekly | biweekly | semi_monthly | monthly · default "monthly"
Used to report per-paycheck amounts alongside annual ones.

target

Works backwards from a take-home goal, annual or per paycheck, to the lowest gross salary that reaches it, with the full breakdown at that salary.

GET https://income-tax.org/api/target?take_home=6000&target_period=monthly&state=texas

Try this example

take_homerequired · number
Desired take-home pay in dollars, after all taxes and the retirement contribution, per target_period.
target_periodoptional · annual | weekly | biweekly | semi_monthly | monthly · default "annual"
Whether take_home is a yearly figure or a per-paycheck one (weekly, biweekly, semi_monthly, monthly).
staterequired · one of 51 values, e.g. alabama, alaska
US state, or district_of_columbia, in snake_case, e.g. new_york. States without an income tax (texas, florida, ...) are valid.
cityoptional · string
Optional city or county with its own local taxes, in snake_case, e.g. new_york_city. Omit for state-level taxes only. An unknown city returns the list of valid ones for the state.
yearoptional · 2023 | 2024 | 2025 | 2026
Tax year. Defaults to the latest available, 2026.
filing_statusoptional · single | married | married_separately | head_of_household · default "single"
Federal and state filing status.
retirement_contributionoptional · number · default 0
Annual pre-tax 401(k) / traditional IRA contribution in dollars. Reduces income tax but not FICA or other payroll taxes, and is subtracted from take-home. Capped at the year's 401(k) limit.
federal_deductionsoptional · number
Total federal deductions in dollars (itemized, or any custom figure). Omit to use the standard deduction for the filing status.
state_deductionsoptional · number
Total state deductions in dollars. Omit to use the state's own standard deduction, including states that phase it out with income.
exempt_taxesoptional · list of object · default []
Taxes the filer is exempt from, e.g. [{ tax: 'social_security', scope: 'federal' }]. An unknown key returns the list of valid keys for the location.
pay_frequencyoptional · weekly | biweekly | semi_monthly | monthly · default "monthly"
Used to report per-paycheck amounts alongside annual ones.

tax_tables

The brackets, rates, standard deductions, credits and 401(k) limit the calculator uses, plus the state's sales tax rates, for a year, state and optional city. Each schedule says how it is applied and what income it is charged on. Unfiltered tables are also free static files, e.g. /data/tax-tables/2026/oregon/portland.json.

GET https://income-tax.org/api/tax-tables?state=oregon&city=portland&filing_status=single

Try this example

yearoptional · 2023 | 2024 | 2025 | 2026
Tax year. Defaults to the latest available, 2026.
stateoptional · one of 51 values, e.g. alabama, alaska
US state in snake_case, e.g. new_york. Omit for federal tables only.
cityoptional · string
Optional city or county, e.g. new_york_city, to include its local tables, or a city with its own sales tax rate, e.g. seattle. Without one, the response lists the state's cities so you can ask again.
filing_statusoptional · single | married | married_separately | head_of_household
Return only the schedules for this filing status. Omit for all four.
tax_typesoptional · list of string
Return only these tax types, e.g. ['federal_income', 'state_income'], or ['sales_tax'] for the state's sales tax rates alone. Omit for all. Unknown keys return the valid ones.

MCP server

The same three endpoints are MCP tools. Add this URL as a custom connector, or remote MCP server, in Claude, ChatGPT, Cursor or any other MCP client. It uses Streamable HTTP and needs no authentication. Use this where an assistant cannot fetch a URL it builds itself: claude.ai chat, for one.

https://income-tax.org/mcp

Tools: calculate, target and tax_tables, taking the parameters above.

Errors and limits

A request the API cannot answer returns HTTP 400 with an error message and, where it applies, the list of valid_values, such as the cities a state has local tax data for. Through MCP the same message comes back as a tool error.

Results are estimates for a single wage earner, with the same simplifications as the calculator. See the disclaimer before relying on them. A summary for language models is at /llms.txt.