Israel Tax Refund — AI-Assisted Filing

Hebrew supported — If you speak Hebrew, Claude will respond in Hebrew. See also: README בעברית

An agentic Claude Code workspace that automates the Israeli tax refund process. Clone the repo, open a Claude session, and let Claude navigate the tax authority website on your behalf using Playwright.

How It Works

1. You clone this repo and open it in Claude Code
2. Claude guides you through entering your personal and financial details
3. A Playwright MCP server controls a real browser session
4. Claude navigates the Israeli Tax Authority (Misim) portal, fills in your information, and submits the refund request on your behalf

No coding required on your end.

Prerequisites

Setup

1. Clone the repo

git clone https://github.com/tupe12334/israel-tax-refund.git
cd israel-tax-refund

2. Install Playwright MCP

npm install -g @playwright/mcp

3. Configure the Playwright MCP server in Claude Code

Add the following to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    }
  }
}

Or run the setup command inside Claude Code:

/mcp add playwright npx @playwright/mcp

4. Open Claude Code in this directory

claude .

Usage

Once inside Claude Code, simply tell Claude:

"Help me apply for a tax refund"

Claude will:

• Ask for the required personal information (ID number, income details, bank account for refund)
• Open a browser via Playwright
• Log in to the tax authority portal using your credentials
• Fill out and submit the refund form
• Report back with confirmation details

What You'll Need to Have Ready

• Israeli ID number (מספר זהות)
• Tax year you are claiming for
• Income details (תלושי שכר / Form 106)
• Bank account number for the refund deposit
• Access to your email/phone for OTP verification during login

Privacy & Security

• Your personal data is only used during the active Claude session and is never stored in this repository
• The browser session runs locally on your machine via Playwright
• No credentials are sent to any third-party service — Claude interacts with the official government portal directly through your local browser

Troubleshooting

Playwright MCP not connecting
Make sure the MCP server is listed under /mcp in Claude Code and shows a green status. If not, restart Claude Code after updating settings.json.

Login OTP not arriving
The tax authority portal sends OTP to the phone number registered on your ID. Make sure your details are up to date at misim.gov.il.

Session timeout
Government portals often have short session windows. If Claude loses the session mid-flow, ask it to restart the browser and try again.

Contributing

Improvements to the CLAUDE.md instructions, skills, or Playwright flow are welcome. Open a PR or issue on tupe12334/israel-tax-refund.

Disclaimer

This tool automates interaction with publicly accessible government web portals on your behalf. You are responsible for the accuracy of the information you provide. This is not legal or tax advice.

License

Released under the PolyForm Noncommercial License 1.0.0. You may use, modify, and share this project for personal and other noncommercial purposes only. Commercial use — including using it to file returns on behalf of paying clients, bundling it into a paid product or service, or any other use intended for commercial advantage — is not permitted without a separate written license from the author.