🏛️ irs-taxpayer-mcp
An open-source tax estimation and planning assistant for US individual taxpayers using Model Context Protocol.
Power your agent
पब्लिशर की अपनी कमांड। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
npx -y [email protected]Claude Code में लोकल कमांड के लिए इंस्टॉल लिंक नहीं है। नीचे दी गई कमांड कॉपी करें और टर्मिनल में चलाएँ।
claude mcp add irs-taxpayer-mcp -- npx -y irs-taxpayer-mcp@1.2.7टर्मिनल में चलाएँ।
{ "mcpServers": { "irs-taxpayer-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्च⚠️ Disclaimer: This tool provides estimates for educational and informational purposes only. It does not constitute tax, legal, or financial advice. Always consult a qualified tax professional.
Legal Notice: This software is provided "as is" without warranty of any kind. The authors and contributors are not tax professionals, CPAs, enrolled agents, or attorneys. No attorney-client, CPA-client, or fiduciary relationship is created by using this software. Tax laws change frequently and vary by jurisdiction. The calculations may contain errors, omissions, or may not reflect the most recent legislative changes. You are solely responsible for your tax filing decisions. The authors disclaim all liability for any damages arising from the use of this software. See DISCLAIMER.md for full legal notice.
Tax season is stressful. You're juggling W-2s, 1099s, deductions, credits, and trying to figure out if you should itemize or take the standard deduction. You Google "SALT deduction limit 2025" and get 10 conflicting articles.
This package provides a deterministic local tax engine with two interfaces. Direct local CLI commands can collect, validate, import, and calculate supported tax facts without invoking an MCP client or model. The MCP server lets an AI assistant call the same engine, but tax facts entered into a cloud-hosted MCP client may be processed by that client's model provider. No IRS login or SSN is required.
It includes OBBB provisions modeled for TY2025, federal brackets, selected credits and deductions, and explicitly supported state-tax paths. Unsupported state calculations fail closed instead of applying a rough top-rate estimate.
Install once, before entering any tax facts:
npm install --global irs-taxpayer-mcp
Run the guided local questionnaire. It does not start MCP or invoke a model:
irs-taxpayer-mcp intake --output taxpayer-facts.json
Or create and edit a strict local template:
irs-taxpayer-mcp template --output taxpayer-facts.json
irs-taxpayer-mcp validate --facts taxpayer-facts.json
Calculate directly through the deterministic engine:
irs-taxpayer-mcp plan --facts taxpayer-facts.json
irs-taxpayer-mcp plan --facts taxpayer-facts.json --json
New facts files are created with mode 0600 on POSIX. On Windows, the CLI rejects existing symbolic links but relies on the current user's filesystem permissions. Existing files are not replaced unless --force is explicit. Imported JSON is limited to 1 MiB, rejects symbolic links and unknown fields, and does not accept names, SSNs, addresses, employer IDs, or account numbers.
Using npx may download the public package before execution, but the direct commands do not send the facts file or its values over the network.
The MCP server makes no network requests and stores no taxpayer data. However, facts typed into an MCP client may be processed by that client's model provider. Use direct local mode or a local-model MCP client when end-to-end local handling is required.
Add this to your MCP client configuration:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"irs-taxpayer": {
"command": "npx",
"args": ["-y", "irs-taxpayer-mcp"]
}
}
}
Kiro (.kiro/settings/mcp.json):
{
"mcpServers": {
"irs-taxpayer": {
"command": "npx",
"args": ["-y", "irs-taxpayer-mcp"]
}
}
}
Cursor: same format in Cursor's MCP settings.
After saving the config, restart the app. The MCP server will auto-download and connect.
The client model converts natural language into tool arguments. Do not enter real taxpayer facts here unless the selected MCP host and model satisfy your privacy requirements:
docker build -t irs-taxpayer-mcp .
docker run -i irs-taxpayer-mcp
npx irs-taxpayer-mcp --http --port 3000
# MCP endpoint: http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/health
HTTP mode is stateless and binds only to a loopback host by default. Browser requests must use an exact allowed Origin. Add a trusted browser Origin with a repeatable flag:
npx irs-taxpayer-mcp --http \
--allowed-origin https://trusted-client.example
The legacy --sse flag remains a deprecated alias for --http. The old /sse and /messages endpoints are not exposed.
All tools use the current MCP registerTool API. Each advertises read-only annotations and an output schema, and returns both human-readable text and structuredContent. Error results include a stable error code, message, and recovery suggestion.
The 1.0 flagship generate_tax_plan workflow returns domain structured results, assumptions, official source provenance, a calculation trace, and explicit unsupported boundaries. The deterministic engine performs no network requests, persistence, or telemetry. Its structured privacy metadata reports whether the MCP adapter or direct CLI path was used. Unsupported tax years, state profiles, and required worksheet facts fail closed. See Local Tax Planner 1.0 Contract.
Supported historical calculation year using IRS Revenue Procedure 2023-34. Standard deduction $14,600 (single) / $29,200 (MFJ). CTC $2,000. SALT cap $10,000.
Reflects OBBB signed July 4, 2025:
Uses IRS Revenue Procedure 2025-32 and the SSA 2026 contribution and benefit base:
This project is a deterministic estimation and planning engine, not tax preparation or filing software.
See ROADMAP.md for the remaining work toward a filing-grade federal return engine.
Numeric regression tests cite IRS Revenue Procedures, IRC sections, and relevant legislation. Reference and planning tools may summarize rules that are not fully represented in the calculation engine.
Requires Node.js 20 or later.
git clone https://github.com/dma9527/irs-taxpayer-mcp.git
cd irs-taxpayer-mcp
npm install
npm run build
npm start # stdio mode
npm run dev # development mode (tsx)
Contributions welcome. Please ensure:
npm test)npm run build)any types in TypeScriptSee CONTRIBUTING.md for full guidelines.
Deterministic local US individual tax engine with direct no-model CLI and MCP adapters for supported TY2024 through TY2026 scenarios
{ "mcpServers": { "irs-taxpayer-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Irs Taxpayer stdio पर लोकल चलता है।
पिछली जाँच 2026-11-17 को हुई। Deterministic local US individual tax engine with direct no-model CLI and MCP adapters for supported TY2024 through TY2026 scenarios