🏛️ irs-taxpayer-mcp
An open-source tax estimation and planning assistant for US individual taxpayers using Model Context Protocol.
接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
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 还是本机命令? 两种安装方式的区别
⚠️ 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]" ] } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 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