# MMEX MCP Server

MCP (Model Context Protocol) Server for interacting with Money Manager EX databases.

---

### 🌐 Documentación en Español (Spanish)
Toda la documentación detallada y guías en español están disponibles en:
👉 **[README_es.md](README_es.md)**

---

## Requirements

- Python 3.10+
- A Money Manager EX database file (.mmb)

## Installation

You can install the server directly from PyPI:

```bash
pip install mmex-mcp
```

Or using `uv` (recommended):

```bash
uv tool install mmex-mcp
```

## Configuration

Set the `MMEX_DB_PATH` environment variable to point to your database:

```bash
export MMEX_DB_PATH=/path/to/your/database.mmb
```

For encrypted databases, also set `MMEX_DB_KEY`:

```bash
export MMEX_DB_KEY=your_password
```

## Using with MCP Clients

### OpenCode
```json
{
    "mcp": {
        "mmex-mcp": {
            "enabled": true,
            "type": "local",
            "command": [
                "mmex-mcp"
            ],
            "environment": {
                "MMEX_DB_PATH": "/path/to/your/database.mmb"// Optional
            }
        }
    }
}
```

### Claude Desktop

Since `mmex-mcp` is installed as a system package or via `uv tool`, you can configure Claude Desktop to use it directly.

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "mmex-mcp": {
      "command": "mmex-mcp",
      "env": {
        "MMEX_DB_PATH": "/path/to/your/database.mmb"//Optional
      }
    }
  }
}
```

### Other MCP Clients

For clients that support stdio MCP servers:

```bash
MMEX_DB_PATH=/path/to/file.mmb mmex-mcp
```

## Testing

### Using MCP Inspector (Recommended)

The MCP Inspector provides a web UI to test all tools interactively:

```bash
MMEX_DB_PATH=/path/to/file.mmb npx @modelcontextprotocol/inspector mmex-mcp
```

This will:
1. Start the MCP server
2. Launch the MCP Inspector web UI
3. Open your browser at the provided localhost URL.

## Available Tools

| Category | Tools |
|----------|-------|
| **Support** | `mmex_support_get_db_version` |
| **Currencies** | `mmex_currencies_list`, `mmex_currencies_get`, `mmex_currencies_by_symbol`, `mmex_currencies_create`, `mmex_currencies_update`, `mmex_currencies_delete` |
| **Tags** | `mmex_tags_list`, `mmex_tags_get`, `mmex_tags_create`, `mmex_tags_update`, `mmex_tags_delete`, `mmex_tags_for_reference`, `mmex_tags_link`, `mmex_tags_unlink` |
| **Categories** | `mmex_categories_list`, `mmex_categories_get`, `mmex_categories_subcategories`, `mmex_categories_create`, `mmex_categories_update`, `mmex_categories_delete` |
| **Payees** | `mmex_payees_list`, `mmex_payees_get`, `mmex_payees_create`, `mmex_payees_update`, `mmex_payees_delete` |
| **Accounts** | `mmex_accounts_list`, `mmex_accounts_get`, `mmex_accounts_balance`, `mmex_accounts_create`, `mmex_accounts_update`, `mmex_accounts_update_partial`, `mmex_accounts_delete` |
| **Assets** | `mmex_assets_list`, `mmex_assets_get`, `mmex_assets_create`, `mmex_assets_update`, `mmex_assets_delete` |
| **Stocks** | `mmex_stocks_list`, `mmex_stocks_get`, `mmex_stocks_create`, `mmex_stocks_update`, `mmex_stocks_delete` |
| **Transactions** | `mmex_transactions_list`, `mmex_transactions_get`, `mmex_transactions_create`, `mmex_transactions_update`, `mmex_transactions_delete`, `mmex_transactions_splits`, `mmex_transactions_add_split`, `mmex_transactions_update_split`, `mmex_transactions_delete_split`, `mmex_transactions_tags`, `mmex_transactions_link_tag`, `mmex_transactions_unlink_tag` |
| **Scheduled** | `mmex_scheduled_list`, `mmex_scheduled_get`, `mmex_scheduled_create`, `mmex_scheduled_update`, `mmex_scheduled_delete` |

**Total: 60 tools**

## Documentation

See [docs/](docs/) for detailed documentation:
- [docs/README.md](docs/README.md) - Overview
- [docs/design.md](docs/design.md) - Technical design
- [docs/implementation-plan.md](docs/implementation-plan.md) - Implementation details
- [docs/README_es.md](docs/README_es.md) - Visión General (Español)
- [docs/design_es.md](docs/design_es.md) - Diseño Técnico (Español)
- [docs/implementation-plan_es.md](docs/implementation-plan_es.md) - Plan de Implementación (Español)

## Development

If you want to contribute or build from source:

```bash
git clone https://github.com/PatricioRios/mmex_mcp
cd mmex_mcp
uv sync
MMEX_DB_PATH=/path/to/file.mmb uv run mcp dev src/mmex_mcp/server.py
```