Metadata-Version: 2.5
Name: degiro-mcp
Version: 0.1.0
Summary: Read-only MCP server for your DEGIRO account: portfolio, cash, trades, dividends.
Project-URL: Homepage, https://github.com/ivanrad07/degiro-mcp
Project-URL: Issues, https://github.com/ivanrad07/degiro-mcp/issues
Author: Ivan Radulovic
License-Expression: MIT
License-File: LICENSE
Keywords: broker,claude,degiro,mcp,model-context-protocol,portfolio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: degiro-connector<4,>=3.0.36
Requires-Dist: mcp<3,>=2.2
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: requests<3,>=2.32.5
Description-Content-Type: text/markdown

# degiro-mcp

A read-only [MCP](https://modelcontextprotocol.io) server for your DEGIRO account. It lets Claude (or any MCP client) answer questions about your holdings, cash, trades and dividends.

> **Unofficial, and you use it at your own risk.** This project is not affiliated with or endorsed by DEGIRO or flatexDEGIRO Bank. Read the [Disclaimer](#disclaimer) before you give it your login.

## Read-only by design

Your DEGIRO login can trade, so this server makes sure it never does:

- **No write tools.** It has no tools to place, change or cancel orders, or to edit favourites or notes.
- **An HTTP guard blocks everything else.** Every request the server's DEGIRO session sends is checked before it leaves your machine. Only GETs to `trader.degiro.nl` and DEGIRO's price feed, the login call and the product-details lookup get through. Any other request is refused and reported as an error, even if a future code change tries to send it. The one request that skips the guard is a plain GET: when DEGIRO answers a login with "under maintenance", degiro-connector fetches the maintenance page to show you its text.
- **Your credentials stay with you.** They are read from environment variables or the macOS Keychain and sent only to DEGIRO.
- **No lockout from retries.** If DEGIRO rejects your credentials, the server never sends the same ones again.

## Tools

| Tool | What it returns |
|---|---|
| `get_portfolio` | Holdings: product (name, ISIN, ticker), size, live price, value, break-even price, total and today's P/L, and cash |
| `get_account_summary` | Totals: cash, free space to trade, net deposits, fees |
| `get_transactions` | Executed trades between two dates, with fees and FX |
| `get_cash_movements` | Every cash movement between two dates: deposits, dividends, dividend tax, fees, FX |
| `get_open_orders` | Orders that haven't been executed or cancelled yet |
| `get_order_history` | Orders placed, changed or cancelled between two dates |
| `get_upcoming_payments` | Dividends that are announced but not yet paid |
| `search_products` | Find a product by name, ticker or ISIN |

Fields ending in `_base` are in your account's base currency. Date ranges end today unless you pass `to_date`, and start on 1 January of the end date's year unless you pass `from_date`.

`get_portfolio` prices positions the way the DEGIRO app does, from DEGIRO's own price feed. Each position's `price_quality` is `REALTIME` or `DELAYED` (15 minutes), depending on your DEGIRO market-data subscription. It is `CLOSE` when the feed has no price, and the position is then valued at the last close.

## Setup

You need [uv](https://docs.astral.sh/uv/). Choose how you log in:

| Your DEGIRO login | Set | Behaviour |
|---|---|---|
| 2FA with an authenticator app | `DEGIRO_TOTP_SECRET` | Fully automatic (recommended) |
| No 2FA (you approve logins in the DEGIRO app) | nothing extra | The first tool call waits up to 90 s for you to tap **Yes** in the app. You'll be asked again after 30 minutes of inactivity. |

`DEGIRO_TOTP_SECRET` is the 32-character setup key DEGIRO shows when you turn on 2FA. You can also take it from the `secret=` part of the QR code. DEGIRO shows it only once, so if you don't have it you'll need to switch 2FA off and on again. Add the new code to your authenticator app at the same time.

### Claude Code

```sh
claude mcp add degiro \
  -e DEGIRO_USERNAME=your-username \
  -e DEGIRO_PASSWORD='your-password' \
  -e DEGIRO_TOTP_SECRET=YOURSETUPKEY \
  -- uvx degiro-mcp
```

### Claude Desktop and other clients

```json
{
  "mcpServers": {
    "degiro": {
      "command": "uvx",
      "args": ["degiro-mcp"],
      "env": {
        "DEGIRO_USERNAME": "your-username",
        "DEGIRO_PASSWORD": "your-password",
        "DEGIRO_TOTP_SECRET": "YOURSETUPKEY"
      }
    }
  }
}
```

### macOS Keychain (keeps the password out of config files)

```sh
security add-generic-password -s degiro-mcp -a DEGIRO_USERNAME -w   # prompts for the value
security add-generic-password -s degiro-mcp -a DEGIRO_PASSWORD -w
security add-generic-password -s degiro-mcp -a DEGIRO_TOTP_SECRET -w   # optional
claude mcp add degiro -e DEGIRO_KEYCHAIN_SERVICE=degiro-mcp -- uvx degiro-mcp
```

## Configuration

| Variable | Required | Meaning |
|---|---|---|
| `DEGIRO_USERNAME` | yes | Your DEGIRO username |
| `DEGIRO_PASSWORD` | yes | Your DEGIRO password |
| `DEGIRO_TOTP_SECRET` | no | 2FA setup key, for automatic logins |
| `DEGIRO_INT_ACCOUNT` | no | Account number; looked up automatically if not set |
| `DEGIRO_KEYCHAIN_SERVICE` | no | macOS Keychain service to read any of the four above from |
| `DEGIRO_APP_APPROVAL_TIMEOUT` | no | Seconds to wait for in-app approval, 5 to 600 (default 90) |
| `DEGIRO_MCP_DEBUG` | no | Set to `1` for verbose library logs on stderr. These logs include session ids. |

## Troubleshooting

- **"DEGIRO wants a captcha"**: log in once at trader.degiro.nl in a browser, then try again.
- **"DEGIRO rejected the username, password or 2FA key"**: fix the credentials. The server won't resend rejected ones. A Keychain change takes effect on the next call; an env var change needs a restart of your MCP client.
- **Scheduled maintenance**: DEGIRO's API is down during its maintenance windows. Try again later.

## Development

```sh
uv run --group dev pytest
```

## Disclaimer

- **Unofficial.** This is a community project. It is not affiliated with, endorsed by or supported by DEGIRO or flatexDEGIRO Bank. "DEGIRO" is used only to say which service the software works with.
- **No public API.** DEGIRO doesn't offer one. This server uses the community [degiro-connector](https://github.com/Chavithra/degiro-connector) library, which talks to the same private endpoints as DEGIRO's website and app. DEGIRO can change them at any time, and the server can stop working without notice.
- **Check DEGIRO's terms.** Automated access to your account may not be allowed by DEGIRO's terms of service. Read them before you use this. Your account is your responsibility, including any restriction or lockout DEGIRO applies to it.
- **Use at your own risk.** The software is provided "as is", without warranty of any kind (see the [MIT license](LICENSE)). The authors are not liable for any loss, including financial loss, account restrictions or exposed credentials.
- **Not financial advice.** Nothing this server or an AI assistant using it tells you is investment advice. Prices can be delayed, so check figures in DEGIRO before you act on them.

## License

[MIT](LICENSE)
