finance-mcp-server

A standalone MCP (Model Context Protocol) server that exposes an H2 database as a set of tools an LLM can call: list_tables, describe_table, run_query, run_update, sample_rows.

This is intentionally a separate Python process/repo from the Java service — they only share the H2 database itself.

Important: running alongside a Java service

Embedded H2 (jdbc:h2:./data/mydb) locks the database file for a single process. If your Java service opens H2 that way, this Python server can't connect to the same file at the same time. Two ways around that:

Option A — H2 TCP server mode (recommended for this setup) Run H2 as a small server process; both your Java app and this MCP server connect to it over TCP as clients:

java -cp h2-2.2.224.jar org.h2.tools.Server \
  -tcp -tcpAllowOthers -ifNotExists

Then both sides use a URL like:

jdbc:h2:tcp://localhost:9092/./data/mydb

Option B — AUTO_SERVER=TRUE Keep the embedded URL in your Java app but append ;AUTO_SERVER=TRUE. H2 will then also accept other connections to the same file.

This project defaults to Option A (see .env.example).

Setup

# 1. Get the H2 driver jar (match your H2 version)
mkdir -p drivers
curl -L -o drivers/h2.jar \
  https://repo1.maven.org/maven2/com/h2database/h2/2.2.224/h2-2.2.224.jar

# 2. Python env
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. Configure
cp .env.example .env
# edit .env if your JDBC URL / credentials differ

# 4. Fetch the H2 driver JAR **before** first startup
This is a required step — the server will fail to start (or fail to connect) without the H2 jar present.
```bash
scripts\fetch_h2_driver.sh

⚠️ Known issue: a missing or wrong H2 jar version was the main setup blocker. Make sure fetch_h2_driver.sh completes successfully and downloads the jar version your H2 database file was created with — a version mismatch between the driver jar and the .mv.db file format will cause connection failures. Confirm the jar lands wherever server.py expects it (check the script/config for the exact path) before moving on.

5. Start H2 in TCP server mode (separate terminal), then run:

python server.py

`jaydebeapi` starts an embedded JVM to load the H2 driver, so you need a
JDK/JRE installed and on `PATH` (or `JAVA_HOME` set) — this is separate
from whatever JVM your Java service runs under.

## Trying it with Claude Desktop

Add to your Claude Desktop MCP config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on
macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "h2-database": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/h2-mcp-server/server.py"],
      "env": {
        "H2_JDBC_URL": "jdbc:h2:tcp://localhost:9092/./data/mydb",
        "H2_USER": "sa",
        "H2_PASSWORD": "",
        "H2_ALLOW_WRITES": "false"
      }
    }
  }
}

Restart Claude Desktop, then ask it something like "what tables are in my H2 database?" — it will call list_tables / describe_table / run_query as needed.

Safety notes

• run_query only accepts SELECT statements.
• run_update (INSERT/UPDATE/DELETE/MERGE) is disabled by default — set H2_ALLOW_WRITES=true to turn it on.
• Both tools block DROP, TRUNCATE, ALTER, GRANT, REVOKE, SHUTDOWN, and user-management statements outright.
• This is demo-grade guarding (regex-based), not a substitute for a real permissions model — don't point it at a production database with real user data without tightening this further.

Moving to AWS later

Swap the last line of server.py:

mcp.run(transport="stdio")

for:

mcp.run(transport="streamable-http")

and put it behind whatever orchestrator/API layer talks to your LLM provider — stdio only works for local parent/child process setups.