# agigante80/actual-mcp-server architecture

> Architecture diagram of the GitHub repository agigante80/actual-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agigante80/actual-mcp-server
- Repository: https://github.com/agigante80/actual-mcp-server

## Overview

Actual MCP Server exposes Actual Budget operations to MCP-compatible assistants over HTTP or stdio. Requests enter through a transport, are dispatched to registered tools, and use the Actual adapter and connection management to query or update the upstream budget. The graph preserves documented tool domains and OIDC/ACL support; several domain implementations are represented by their exact source directory because their individual files were not excerpted. Links are limited to excerpted or README-supported relationships.

Main entry points: [`src/server/httpServer.ts`](https://github.com/agigante80/actual-mcp-server/blob/main/src/server/httpServer.ts) (HTTP transport), [`src/tools/index.ts`](https://github.com/agigante80/actual-mcp-server/blob/main/src/tools/index.ts) (Tool registry), [`src/lib/actual-adapter.ts`](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/actual-adapter.ts) (Actual API adapter), [`src/actualToolsManager.ts`](https://github.com/agigante80/actual-mcp-server/blob/main/src/actualToolsManager.ts) (Tool dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entrypoints"]
  node_http["HTTP transport<br/>[httpServer.ts]"]
  node_stdio["stdio transport<br/>[stdioServer.ts]"]
  node_bootstrap["Server bootstrap<br/>[index.ts]"]
end

subgraph group_security["Identity and access"]
  node_auth["OIDC and ACL"]
  node_context["Request context<br/>[requestContext.ts]"]
end

subgraph group_tools["Budget capabilities"]
  node_manager["Tool dispatcher"]
  node_registry["Tool registry<br/>[index.ts]"]
  node_budget["Budget operations"]
  node_transactions["Transaction operations"]
  node_accounts["Accounts and entities"]
  node_analysis["Queries and summaries"]
end

subgraph group_runtime["Actual integration"]
  node_adapter["Actual API adapter<br/>[actual-adapter.ts]"]
  node_connections["Session connections"]
  node_connection["Connection lifecycle"]
  node_querycheck["Query validation<br/>[query-validator.ts]"]
  node_schema["Actual schema<br/>[actual-schema.ts]"]
end

subgraph group_support["Shared runtime"]
  node_config["Configuration<br/>[config.ts]"]
  node_logging["Logging and observability<br/>[logger.ts]"]
end

node_assistant(("MCP assistant"))
node_actual["Actual Budget server"]

node_assistant -->|"MCP over HTTP"| node_http
node_assistant -->|"MCP over stdio"| node_stdio
node_bootstrap -->|"starts"| node_http
node_bootstrap -->|"starts"| node_stdio
node_http -->|"validates access"| node_auth
node_http -->|"sets request scope"| node_context
node_http -->|"initializes sessions"| node_connections
node_http -->|"dispatches tools"| node_manager
node_stdio -->|"dispatches tools"| node_manager
node_manager -->|"loads tools"| node_registry
node_registry -->|"registers"| node_budget
node_registry -->|"registers"| node_transactions
node_registry -->|"registers"| node_accounts
node_registry -->|"registers"| node_analysis
node_manager -.->|"executes tool calls"| node_adapter
node_analysis -->|"validates queries"| node_querycheck
node_querycheck -->|"checks schema"| node_schema
node_connection -->|"connects and loads budget"| node_actual
node_connections -->|"manages sessions"| node_connection
node_adapter -->|"queries and syncs"| node_actual
node_adapter -->|"uses session pool"| node_connections
node_adapter -->|"reads request scope"| node_context
node_auth -->|"uses settings"| node_config
node_http -->|"reads settings"| node_config
node_bootstrap -->|"logs startup"| node_logging

click node_http "https://github.com/agigante80/actual-mcp-server/blob/main/src/server/httpServer.ts"
click node_stdio "https://github.com/agigante80/actual-mcp-server/blob/main/src/server/stdioServer.ts"
click node_bootstrap "https://github.com/agigante80/actual-mcp-server/blob/main/src/index.ts"
click node_auth "https://github.com/agigante80/actual-mcp-server/tree/main/src/auth"
click node_context "https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/requestContext.ts"
click node_manager "https://github.com/agigante80/actual-mcp-server/blob/main/src/actualToolsManager.ts"
click node_registry "https://github.com/agigante80/actual-mcp-server/blob/main/src/tools/index.ts"
click node_budget "https://github.com/agigante80/actual-mcp-server/tree/main/src/tools"
click node_transactions "https://github.com/agigante80/actual-mcp-server/tree/main/src/tools"
click node_accounts "https://github.com/agigante80/actual-mcp-server/tree/main/src/tools"
click node_analysis "https://github.com/agigante80/actual-mcp-server/tree/main/src/tools"
click node_adapter "https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/actual-adapter.ts"
click node_connections "https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/ActualConnectionPool.ts"
click node_connection "https://github.com/agigante80/actual-mcp-server/blob/main/src/actualConnection.ts"
click node_querycheck "https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/query-validator.ts"
click node_schema "https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/actual-schema.ts"
click node_config "https://github.com/agigante80/actual-mcp-server/blob/main/src/config.ts"
click node_logging "https://github.com/agigante80/actual-mcp-server/blob/main/src/logger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http,node_stdio,node_bootstrap toneBlue
class node_auth,node_context toneAmber
class node_manager,node_registry,node_budget,node_transactions,node_accounts,node_analysis,node_actual toneMint
class node_adapter,node_connections,node_connection,node_querycheck,node_schema toneRose
class node_config,node_logging,node_assistant toneIndigo
```

## Components

### MCP entrypoints

- [HTTP transport](https://github.com/agigante80/actual-mcp-server/blob/main/src/server/httpServer.ts): `src/server/httpServer.ts`
- [stdio transport](https://github.com/agigante80/actual-mcp-server/blob/main/src/server/stdioServer.ts): `src/server/stdioServer.ts`
- [Server bootstrap](https://github.com/agigante80/actual-mcp-server/blob/main/src/index.ts): `src/index.ts`

### Identity and access

- [OIDC and ACL](https://github.com/agigante80/actual-mcp-server/tree/main/src/auth): `src/auth`
- [Request context](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/requestContext.ts): `src/lib/requestContext.ts`

### Budget capabilities

- [Tool dispatcher](https://github.com/agigante80/actual-mcp-server/blob/main/src/actualToolsManager.ts): `src/actualToolsManager.ts`
- [Tool registry](https://github.com/agigante80/actual-mcp-server/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Budget operations](https://github.com/agigante80/actual-mcp-server/tree/main/src/tools): `src/tools`
- [Transaction operations](https://github.com/agigante80/actual-mcp-server/tree/main/src/tools): `src/tools`
- [Accounts and entities](https://github.com/agigante80/actual-mcp-server/tree/main/src/tools): `src/tools`
- [Queries and summaries](https://github.com/agigante80/actual-mcp-server/tree/main/src/tools): `src/tools`

### Actual integration

- [Actual API adapter](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/actual-adapter.ts): `src/lib/actual-adapter.ts`
- [Session connections](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/ActualConnectionPool.ts): `src/lib/ActualConnectionPool.ts`
- [Connection lifecycle](https://github.com/agigante80/actual-mcp-server/blob/main/src/actualConnection.ts): `src/actualConnection.ts`
- [Query validation](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/query-validator.ts): `src/lib/query-validator.ts`
- [Actual schema](https://github.com/agigante80/actual-mcp-server/blob/main/src/lib/actual-schema.ts): `src/lib/actual-schema.ts`

### Shared runtime

- [Configuration](https://github.com/agigante80/actual-mcp-server/blob/main/src/config.ts): `src/config.ts`
- [Logging and observability](https://github.com/agigante80/actual-mcp-server/blob/main/src/logger.ts): `src/logger.ts`

### Other components

- **MCP assistant**
- **Actual Budget server**

## Connections

- MCP assistant → HTTP transport: MCP over HTTP
- MCP assistant → stdio transport: MCP over stdio
- Server bootstrap → HTTP transport: starts (evidence: `src/index.ts`)
- Server bootstrap → stdio transport: starts (evidence: `src/index.ts`)
- HTTP transport → OIDC and ACL: validates access (evidence: `src/server/httpServer.ts`)
- HTTP transport → Request context: sets request scope (evidence: `src/lib/requestContext.ts`)
- HTTP transport → Session connections: initializes sessions (evidence: `src/server/httpServer.ts`)
- HTTP transport → Tool dispatcher: dispatches tools (evidence: `src/server/httpServer.ts`)
- stdio transport → Tool dispatcher: dispatches tools (evidence: `src/server/stdioServer.ts`)
- Tool dispatcher → Tool registry: loads tools (evidence: `src/actualToolsManager.ts`)
- Tool registry → Budget operations: registers (evidence: `src/tools/index.ts`)
- Tool registry → Transaction operations: registers (evidence: `src/tools/index.ts`)
- Tool registry → Accounts and entities: registers (evidence: `src/tools/index.ts`)
- Tool registry → Queries and summaries: registers (evidence: `src/tools/index.ts`)
- Tool dispatcher → Actual API adapter: executes tool calls
- Queries and summaries → Query validation: validates queries (evidence: `src/tools/query_run.ts`)
- Query validation → Actual schema: checks schema (evidence: `src/lib/query-validator.ts`)
- Connection lifecycle → Actual Budget server: connects and loads budget
- Session connections → Connection lifecycle: manages sessions (evidence: `src/lib/ActualConnectionPool.ts`)
- Actual API adapter → Actual Budget server: queries and syncs
- Actual API adapter → Session connections: uses session pool (evidence: `src/lib/actual-adapter.ts`)
- Actual API adapter → Request context: reads request scope (evidence: `src/lib/requestContext.ts`)
- OIDC and ACL → Configuration: uses settings (evidence: `src/auth/budget-acl-dynamic.ts`)
- HTTP transport → Configuration: reads settings (evidence: `src/server/httpServer.ts`)
- Server bootstrap → Logging and observability: logs startup (evidence: `src/index.ts`)
