finanzas-pyme
This server is a read-only MCP finance assistant for a simulated small bakery, answering cash-flow questions in Spanish with data from a local SQLite database.
desglose_gastos: Breaks down monthly expenses by category with percentages, fixed/variable split, top suppliers, and largest individual movements; optionally compares to the previous month and 3-month average.
tendencia_ingresos: Analyzes whether income is growing or falling using month-over-month change, year-over-year comparison, and least-squares trend with R² reliability.
proyeccion_flujo_caja: Projects future cash flow for 1–6 months, modeling seasonal income trends, fixed costs per category (including Bono 14/aguinaldo), variable costs as a share of income, and running balances with coverage status.
estado_resultados: Generates a profit-and-loss statement for a month: income by category, expenses tagged fixed/variable, net profit, margin, and previous-month comparison.
detectar_gastos_atipicos: Flags unusual expense months per category using z-scores against each category's own historical distribution, with a configurable threshold.
salud_financiera: Provides an overall financial health summary: 6-month averages, net margin, fixed-cost coverage, payroll weight, and loss-making months in the last year.
revision_mensual: Delivers a reusable instruction that walks through a full monthly review (income statement, expenses, trend, anomalies, and follow-ups).
Static resources: Exposes the database schema, category catalog, and available months via
finanzas://resources.Local and synthetic: No network access, no credentials, no personal data; the database is built automatically on first use and the server is read-only.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@finanzas-pyme ¿Cuánto gasté en julio?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
finanzas-mcp — SME finance assistant (MCP server)
An MCP (Model Context Protocol) server that lets an LLM answer real finance questions for a small business owner with no accountant: what did I spend last month and on what, are my sales growing, and will I have enough money next month?
It runs locally over the stdio transport and speaks JSON-RPC 2.0, so any MCP host — Claude Desktop, VS Code, or a custom chatbot — can use it.
What it does
The server does not just run SELECTs. Each tool applies a documented method and returns a report that states its own assumptions:
Tool | Question it answers | Method |
| "How much did I spend in July, and on what?" | Category breakdown with shares, fixed/variable split, comparison against the previous month and the 3-month average |
| "Are my sales growing or falling?" | Month-over-month, year-over-year, and a least-squares trend reported with its R² |
| "Will I have enough money next month?" | Income as a damped seasonal trend; fixed costs as level × seasonal index; variable costs as a median share of income |
| "Did I make or lose money in May?" | Profit-and-loss statement with net margin |
| "Was there any unusual expense?" | Per-category z-scores against each category's own history |
| "How is my business doing overall?" | Trailing averages, fixed-cost coverage, payroll weight, loss-making months |
Related MCP server: Expense Manager MCP Server
The simulated business
"Panadería La Espiga", a small bakery. Covering 2025-01 to 2026-08 (20 months, 1,088 transactions).
Installation
Requires Python 3.10+. No database server and no API key: the SQLite file is built automatically on first run from the two bundled SQL scripts.
The dependency is pinned to
mcp>=1.27,<2. The MCP Python SDK v2 renamedFastMCPtoMCPServerand changed several public field names; an unpinned install picks up 2.x and fails at import.
Use it as a dependency
If you only want to use this server, one command is enough — no clone, no database setup, no API key:
pip install git+https://github.com/JuanDsm04/mcp-finanzas-pyme.gitThat installs the package and creates a finanzas-mcp executable in your
environment, which is what you point your MCP host at.
Develop on it
git clone https://github.com/JuanDsm04/mcp-finanzas-pyme.git
cd mcp-finanzas-pyme
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Verify it starts:
python -m finanzas_mcp.server --helpConnecting it to a host
Any MCP host (generic stdio entry). After installing, either of these works — the console script, or the module, which is handy when you want to be explicit about which interpreter runs it:
{
"command": "finanzas-mcp",
"args": []
}{
"command": "python",
"args": ["-m", "finanzas_mcp.server"]
}No working directory or PYTHONPATH is needed in either case.
If your host does not inherit the active virtual environment — Claude Desktop does not, and some editors do not either — use absolute paths:
{
"command": "C:\\path\\to\\your\\.venv\\Scripts\\finanzas-mcp.exe",
"args": []
}{
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "finanzas_mcp.server"]
}chatbot-redes — install into the same virtual environment as the chatbot, then flip the registry entry to enabled:
pip install -e ../mcp-finanzas-pyme"finanzas-pyme": {
"enabled": true,
"transport": "stdio",
"description": "Servidor MCP propio: asistente financiero para PYMES",
"command": "python",
"args": ["-m", "finanzas_mcp.server"],
"env": {}
}Check the connection without spending API credits with
python scripts/check_servers.py from the chatbot repo.
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"finanzas-pyme": {
"command": "/absolute/path/to/.venv/bin/finanzas-mcp",
"args": []
}
}
}MCP Inspector — the quickest way to check the server before wiring it into a host:
npx @modelcontextprotocol/inspector finanzas-mcpWhere the database lives
With an editable install the database goes to data/finanzas.db inside the
repository. With a regular install the package lives in site-packages, so it
lands inside the virtual environment instead. Both work; to choose the location
explicitly, pass the flag in args:
{
"command": "finanzas-mcp",
"args": ["--db-path", "C:\\Users\\you\\finanzas.db"]
}Running finanzas-mcp by hand just blocks: it is waiting for JSON-RPC messages
on stdin. That is expected — the host is what launches it. Ctrl+C exits.
Usage
Questions a user can ask in plain language, and the tool that answers them:
You ask | The model calls |
"¿Cuánto gasté en agosto?" |
|
"¿En qué se me fue el dinero el mes pasado?" |
|
"¿Mis ventas están subiendo o bajando?" |
|
"¿Gané dinero en marzo?" |
|
"¿Me va a alcanzar el próximo mes? Tengo Q45,000" |
|
"¿Hubo algún gasto raro este año?" |
|
"¿Cómo va mi negocio?" |
|
Configuration
Variable / flag | Default | Purpose |
|
| Where the SQLite file lives |
| — | Same, as a flag (takes precedence) |
| off | Delete and rebuild the database before starting |
Server specification
Identity and transport
Field | Value |
Server name |
|
Implementation |
|
Protocol | Model Context Protocol over JSON-RPC 2.0 |
Transport | stdio (the host launches the server as a subprocess) |
Launch command |
|
SDK | MCP Python SDK v1 ( |
Capabilities advertised at initialize:
{
"tools": { "listChanged": false },
"resources": { "subscribe": false, "listChanged": false },
"prompts": { "listChanged": false }
}The server also returns an instructions string telling the host that amounts
are in GTQ, that months use YYYY-MM, and that omitting the month selects the
latest month with data. It writes nothing to stdout, since on the stdio transport
stdout is the protocol channel; diagnostics go to stderr.
Tools
desglose_gastos — breaks one month's expenses down by category.
Parameter | Type | Default | Description |
|
|
| Month, |
|
|
| Add comparison vs previous month and 3-month average. |
Returns the total and movement count; the fixed/variable split; a table per category with amount, share, movements and a bar; optionally the comparison block; the top 5 suppliers; the top 5 individual movements. Errors on a malformed month or a month outside the available period.
tendencia_ingresos — analyses whether income is growing or shrinking.
Parameter | Type | Default | Description |
|
|
| Last month of the window, |
|
|
| Window size, 3 to 24. |
Returns the month-over-month change; the year-over-year comparison when 12
months of history exist; the least-squares trend with slope per month, slope as
a percentage of the window average, and R² with a reliability label (alta
≥ 0.7, media ≥ 0.4, baja below). When R² < 0.4 it explicitly warns that the
slope is indicative, not predictive. Errors when meses is outside 3..24 or
there are fewer than 3 months of history.
proyeccion_flujo_caja — projects income, expenses and cash balance.
Parameter | Type | Default | Description |
|
|
| Months to project, 1 to 6. |
|
|
| Cash on hand in GTQ. Null = use the accumulated result of the last 6 months as a proxy (stated in the output). |
|
|
| Trailing months used to fit, 3 to 18. |
Method, printed in the output so it is auditable:
Income — least squares over the last
ventanamonths, extrapolated, then multiplied by the seasonal index of the target calendar month, damped by 0.5 because the history is short.Fixed costs — per category as
level × seasonal_index, where the level is the mean of the trailing window over a zero-filled series and the index is not damped.Variable costs — the median share of income they absorbed over the window, applied to projected income.
Returns a table per projected month (income, fixed, variable, net flow, running
balance); the composition of the first month's fixed costs; a verdict — SI
(covers everything), AJUSTADO (covers fixed but not variable), or NO; the
coverage ratio, runway in months, lowest projected balance; and a warning that
the projection ignores commitments not present in the data. Errors on meses
outside 1..6, ventana outside 3..18, or a negative saldo_inicial.
estado_resultados — profit-and-loss statement for one month.
Parameter | Type | Default | Description |
|
|
| Month, |
Returns income by category with shares; expenses by category tagged fixed or variable, each as a percentage of income; subtotals; net profit or loss and net margin; the previous month for reference.
detectar_gastos_atipicos — flags months where a category deviates from its
own norm.
Parameter | Type | Default | Description |
|
|
| Trailing months to inspect, minimum 3. |
|
|
| Minimum absolute z-score to report. |
For each expense category with at least four observations in the window, monthly
totals are converted to standard scores against that category's own mean and
population standard deviation. Returns a table sorted by |z| plus the individual
transactions explaining the three largest deviations. When nothing exceeds the
threshold it says so and suggests a lower one. Errors on meses < 3 or
umbral_z ≤ 0.
salud_financiera — one-screen snapshot. No parameters. Returns the latest
closed month and available history; 6-month averages for income, expenses and
result; average net margin; average fixed costs and coverage ratio; payroll cost
and its weight over income; loss-making months in the last year; the active
roster.
Resources
URI | MIME type | Content |
|
| The complete DDL (5 tables and the monthly view) |
|
|
|
|
| Months with data, one per line |
Prompts
revision_mensual (mes: string, default "" = latest month) renders a
reusable instruction that walks the model through a full monthly review: income
statement, expense breakdown, income trend, anomaly detection, then three
conclusions and one actionable recommendation in plain language.
Data model
categorias(id, nombre, tipo, es_fijo, descripcion)
proveedores(id, nombre, categoria_id -> categorias, dias_credito, activo)
clientes(id, nombre, segmento, fecha_alta, activo)
empleados(id, nombre, puesto, salario_mensual, fecha_ingreso, fecha_salida, activo)
transacciones(id, fecha, tipo, monto, categoria_id -> categorias,
proveedor_id -> proveedores, cliente_id -> clientes,
metodo_pago, descripcion)
v_resumen_mensual: monthly totals per categorycategorias.tipo and transacciones.tipo are both constrained to
'ingreso' | 'gasto'; categorias.es_fijo is the flag the projection depends
on; transacciones.monto must be positive, with direction carried by tipo.
Indexes exist on fecha, (tipo, fecha) and (categoria_id, fecha), the three
access patterns every tool uses.
The database is built on first use into data/finanzas.db via a temporary file
that is renamed on success, so a crash mid-import cannot leave a half-populated
database.
Security notes
Every SQL statement is parameterised; no tool interpolates model-provided strings into SQL. The server is read-only — no tool writes to the ledger. The database is local and synthetic: no network access, no credentials, no personal data.
Regenerating the dataset
seed.sql is generated, not hand-written. The generator is deterministic, so
re-running it reproduces the same file:
python scripts/generate_seed.py
rm -f data/finanzas.db # rebuilt automatically on the next runTo change the simulated business, edit the constants at the top of
scripts/generate_seed.py: period, categories,
suppliers, customers, payroll, seasonality, growth rate and planted anomalies.
Project structure
mcp-finanzas-pyme/
├── src/finanzas_mcp/
│ ├── schema.sql DDL: 5 tables + 1 view
│ ├── seed.sql DML: generated, 1,088 transactions
│ ├── db.py SQLite access; builds the database on first use
│ ├── analytics.py Trend, seasonality, projection, z-scores
│ ├── formatting.py Text rendering helpers
│ ├── errors.py ToolInputError
│ ├── tools/
│ │ ├── gastos_por_categoria.py desglose_gastos, detectar_gastos_atipicos
│ │ ├── tendencia_ingresos.py tendencia_ingresos, estado_resultados
│ │ └── proyeccion_flujo.py proyeccion_flujo_caja, salud_financiera
│ └── server.py MCP registration + stdio entry point
├── scripts/generate_seed.py
└── docs/ejemplos.md Worked examples with real outputThe layering is deliberate: analytics.py knows nothing about SQL, the tools
know nothing about MCP, and server.py is a thin registration wrapper.
References
Available Tools
6 toolsdesglose_gastosA
Desglosa los gastos de un mes por categoria (proveedores, nomina, servicios, etc.).
Responde preguntas como "cuanto gaste en julio" o "en que se me fue el dinero el mes pasado". Devuelve el total, el reparto por categoria con porcentajes, la separacion entre gastos fijos y variables, los principales proveedores y los movimientos individuales mas grandes.
Args: mes: Mes a analizar en formato 'YYYY-MM' (ej. '2026-08'). Si se omite, se usa el ultimo mes con datos registrados. incluir_comparacion: Si es True, agrega la comparacion contra el mes anterior y contra el promedio de los tres meses previos.
Inputs: mes, incluir_comparacion. Returns: result
detectar_gastos_atipicosA
Detecta gastos inusuales comparando cada categoria contra su propio historial.
Util para responder "hubo algun gasto raro?" o para explicar por que un mes salio mal. Calcula el z-score de cada categoria por mes y reporta las desviaciones que superan el umbral, junto con el movimiento que las explica.
Args: meses: Cuantos meses hacia atras inspeccionar (minimo 3). umbral_z: Desviaciones estandar minimas para reportar un gasto como atipico. 2.0 es estricto; 1.5 muestra mas casos.
Inputs: meses, umbral_z. Returns: result
estado_resultadosA
Genera el estado de resultados de un mes: ingresos, gastos, utilidad y margen.
Responde "gane o perdi dinero en mayo?". Muestra los ingresos y gastos desglosados por categoria, separa gastos fijos de variables y calcula la utilidad neta y el margen, con el mes anterior como referencia.
Args: mes: Mes en formato 'YYYY-MM'. Si se omite, se usa el ultimo mes con datos.
Inputs: mes. Returns: result
proyeccion_flujo_cajaA
Proyecta si alcanzara el dinero para cubrir los gastos del proximo mes.
Responde "me va a alcanzar el mes que viene?". Proyecta los ingresos con una tendencia corregida por estacionalidad, los gastos fijos categoria por categoria (lo que hace que julio con Bono 14 y diciembre con aguinaldo salgan correctos) y los gastos variables como proporcion de los ingresos. Devuelve el flujo neto, el saldo proyectado y una respuesta directa.
Args: meses: Cuantos meses proyectar hacia adelante, entre 1 y 6. saldo_inicial: Saldo en caja al inicio de la proyeccion, en quetzales. Si se omite se usa el resultado acumulado de los ultimos 6 meses como aproximacion, y se advierte en la respuesta. ventana: Cuantos meses de historial usar para ajustar la tendencia (3 a 18).
Inputs: meses, ventana, saldo_inicial. Returns: result
salud_financieraA
Resumen general del negocio en una sola pantalla.
Util como primera llamada cuando el usuario pregunta algo amplio como "como va mi negocio?". Devuelve promedios de los ultimos 6 meses, margen neto, cobertura de gastos fijos, peso de la nomina, meses con perdida en el ultimo ano y la planilla activa.
Inputs: no named parameters. Returns: result
tendencia_ingresosB
Analiza si los ingresos estan creciendo o bajando, con numeros concretos.
Responde "mis ventas van subiendo o bajando?". Entrega tres niveles de evidencia: la variacion contra el mes anterior, la comparacion interanual (que elimina el efecto de la estacionalidad) y una tendencia ajustada por minimos cuadrados con su R2 para indicar que tan confiable es.
Args: mes: Ultimo mes de la ventana de analisis en formato 'YYYY-MM'. Si se omite, se usa el ultimo mes con datos. meses: Tamano de la ventana de analisis, entre 3 y 24 meses.
Inputs: mes, meses. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct financial aspect: expense breakdown, anomaly detection, income statement, revenue trend, cash flow projection, and overall health. While some overlap in scope (e.g., estado_resultados and salud_financiera both provide summaries), their purposes and outputs are clearly differentiated, making misselection unlikely.
All tool names are in Spanish snake_case, following a descriptive noun or verb-noun pattern. They are consistent in style and clarity, though not all adhere to a strict verb_noun convention. The naming is predictable and readable.
Six tools is well-scoped for a financial analysis server. Each tool covers a meaningful analytical function without redundancy, and the count is appropriate for the domain, allowing agents to choose the right tool without overwhelming options.
The tool surface covers core financial analysis needs: expense breakdown, anomaly detection, income statement, revenue trend, cash flow projection, and a health summary. Minor gaps include lack of a dedicated budget comparison or year-over-year P&L tool, but the existing set handles most common queries without dead ends.
Maintenance
Related MCP Connectors
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Ask questions in plain language, get answers from your business database. No SQL required.
Query your books, company data, business health, and ship invoices from your AI assistant.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI assistants to track, query, summarize, and delete personal expenses stored in a local SQLite database via natural language.4-
- FlicenseAqualityDmaintenanceEnables natural language management of personal expenses, including adding, updating, deleting, searching, and summarizing expenses stored in a local SQLite database.6-
- AlicenseAqualityBmaintenancePrivacy-first MCP server for querying personal health and finance data with AI. Built with Python, FastMCP, and SQLite. Local-first and open source.20398 PyPI8MIT
- FlicenseAqualityCmaintenanceEnables LLMs to record, list, update, and delete expenses and credits in a local SQLite database, with enforced categories and running balance summaries.8-