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.jsoncalculate
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_cityincomerequired · 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=texastake_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=singleyearoptional · 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/mcpTools: 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.