API & MCP
The calculator is available to AI assistants and scripts as an MCP server and as plain JSON URLs. It runs the same calculation as this site, needs no API key, and is free to use.
MCP server
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.
https://income-tax.org/mcpIt provides three tools: calculate, target and tax_tables, described below.
JSON URLs
Each tool is also a GET request that returns JSON, for assistants that can fetch a web page but do not support MCP, and for scripts. Lists are comma-separated: exempt_taxes takes scope:tax pairs such as federal:social_security,city:city_income, and tax_types takes plain keys.
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.
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 and 401(k) limit the calculator uses, for a year, state and optional city. Each schedule says how it is applied and what income it is charged on.
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. 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']. Omit for all. Unknown keys return the valid ones.
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.