Content
# drebedengi-mcp
MCP stdio server for the Drebedengi SOAP API.
The server exposes MCP tools for balances, reference lists, transactions, changes, and write operations (expenses, incomes, transfers, tags). Write tools are disabled by default and must be explicitly enabled.
Money fields (`sum`, `difference`) are returned as raw integer strings in minor currency units (kopecks, tiyn, cents). Divide by 100 to get the major unit amount.
## Safety
Read tools are always available. Write tools are gated behind the `DREBEDENGI_ALLOW_WRITES=true` environment variable and are not registered unless explicitly enabled.
Credentials are read only from process environment. They are not accepted as MCP tool arguments.
## Configuration
Required environment variables:
- `DREBEDENGI_API_ID`
- `DREBEDENGI_LOGIN`
- `DREBEDENGI_PASSWORD`
Optional environment variables:
- `DREBEDENGI_WSDL_URL`, default `https://www.drebedengi.ru/soap/dd.wsdl`
- `DREBEDENGI_TIMEOUT_SECONDS`, default `30`
- `DREBEDENGI_ALLOW_WRITES`, default `false` — set to `true` to enable write tools
For local manual runs, copy `.env.example` to `.env` and fill in your credentials. For MCP client usage, prefer passing these variables through the client's `mcpServers` config.
## MCP Client Config
Example:
```json
{
"mcpServers": {
"drebedengi": {
"command": "uv",
"args": [
"--directory",
"/home/koktut/projects/drebedengi_mcp",
"run",
"drebedengi-mcp"
],
"env": {
"DREBEDENGI_API_ID": "...",
"DREBEDENGI_LOGIN": "...",
"DREBEDENGI_PASSWORD": "..."
}
}
}
}
```
## Development
Install dependencies:
```bash
uv sync --extra dev
```
Run tests:
```bash
uv run --extra dev python -m pytest
```
Run the MCP server:
```bash
uv run drebedengi-mcp
```
Do not print to stdout in server code. Stdio MCP uses stdout for JSON-RPC protocol messages.
## Tools
### Read tools (always available)
- `drebedengi_healthcheck` — verifies credentials and returns the current server revision.
- `drebedengi_get_current_revision` — returns the current Drebedengi server revision.
- `drebedengi_get_balance` — returns balances by places/accounts. Optional filters: `rest_date`, `is_with_accum`, `is_with_duty`.
- `drebedengi_list_currencies` — returns currencies. Optional filter: `ids`.
- `drebedengi_list_categories` — returns expense/income categories. Optional filter: `ids`.
- `drebedengi_list_sources` — returns income sources. Optional filter: `ids`.
- `drebedengi_list_places` — returns places/accounts. Optional filter: `ids`.
- `drebedengi_list_tags` — returns tags. Optional filter: `ids`.
- `drebedengi_list_transactions` — returns records by `ids` or report/export filters.
Common export filters: `r_period`, `is_report`, `is_show_duty`, `r_how`, `r_what`,
`r_currency`, `r_is_place`, `r_is_tag`.
- `drebedengi_get_changes` — returns changes after a known `revision`.
### Write tools (require `DREBEDENGI_ALLOW_WRITES=true`)
- `drebedengi_add_expense` — record an expense transaction.
- `drebedengi_add_income` — record an income transaction.
- `drebedengi_add_transfer` — record a transfer between accounts (creates two linked records).
- `drebedengi_set_record` — update an existing transaction record.
- `drebedengi_delete_record` — delete a transaction record by ID.
- `drebedengi_create_tag` — create a new tag.
For a simple transaction export, use the same filter shape as Drebedengi's SOAP example:
```json
{
"r_period": 8,
"is_report": false,
"is_show_duty": true,
"r_how": 1,
"r_what": 6,
"r_currency": 0,
"r_is_place": 0,
"r_is_tag": 0
}
```
## WSDL Coverage
The Drebedengi WSDL (`dd.wsdl`) exposes 34 operations. This server implements 12 of them.
### Implemented
| WSDL operation | MCP tool(s) |
|---|---|
| `getCurrentRevision` | `drebedengi_get_current_revision` |
| `getBalance` | `drebedengi_get_balance` |
| `getCurrencyList` | `drebedengi_list_currencies` |
| `getCategoryList` | `drebedengi_list_categories` |
| `getSourceList` | `drebedengi_list_sources` |
| `getPlaceList` | `drebedengi_list_places` |
| `getTagList` | `drebedengi_list_tags` |
| `getRecordList` | `drebedengi_list_transactions` |
| `getChangeList` | `drebedengi_get_changes` |
| `setRecordList` | `drebedengi_add_expense`, `drebedengi_add_income`, `drebedengi_add_transfer`, `drebedengi_set_record` |
| `setTagList` | `drebedengi_create_tag` |
| `deleteObject` | `drebedengi_delete_record` |
### Not implemented
**Reference list management (write):** `setCategoryList`, `setSourceList`, `setPlaceList`, `setCurrencyList`, `setAccumList`
**Accumulations and orders (read):** `getAccumList`, `getOrderList`
**Checks (receipts):** `getCheckList`, `setCheckList`, `getCheckToRecordList`, `setCheckToRecordList`
**Data parsing:** `parseTextData`, `parsePushData`
**Account/service:** `getAccessStatus`, `getRightAccess`, `getExpireDate`, `getSubscriptionStatus`, `getServerSubs`, `getUserIdByLogin`, `setPaymentTransaction`, `userRegister`
**Dangerous:** `deleteAll`
## SOAP Compatibility
Drebedengi's WSDL declares several arguments and responses as `xsd:anyType`, but the
service expects SOAP encoded arrays and `xml-soap:Map` values. The client normalizes
`params` and `idList` before sending requests and converts XML response items into
JSON-compatible Python dictionaries before returning MCP tool results.
## Real API Smoke Tests
Default tests do not call the real Drebedengi API. Any real network smoke test must be opt-in and marked with `@pytest.mark.smoke`.
Manual real-data smoke checks should use credentials from `.env` or the process
environment. Keep output summaries high level and do not print raw financial records:
```bash
uv run --extra dev python -m pytest
uv run --extra dev drebedengi-mcp
```
