How agigante80/actual-mcp-server works
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: httpServer.ts HTTP transport · index.ts Tool registry · actual-adapter.ts Actual API adapter · actualToolsManager.ts Tool dispatcher
Components 20
MCP entrypoints
- HTTP transport
src/server/httpServer.ts - stdio transport
src/server/stdioServer.ts - Server bootstrap
src/index.ts
Identity and access
- OIDC and ACL
src/auth - Request context
src/lib/requestContext.ts
Budget capabilities
- Tool dispatcher
src/actualToolsManager.ts - Tool registry
src/tools/index.ts - Budget operations
src/tools - Transaction operations
src/tools - Accounts and entities
src/tools - Queries and summaries
src/tools
Actual integration
- Actual API adapter
src/lib/actual-adapter.ts - Session connections
src/lib/ActualConnectionPool.ts - Connection lifecycle
src/actualConnection.ts - Query validation
src/lib/query-validator.ts - Actual schema
src/lib/actual-schema.ts
Shared runtime
- Configuration
src/config.ts - Logging and observability
src/logger.ts
Other components
- MCP assistant
- Actual Budget server
Connections 25
- MCP assistant → HTTP transport: MCP over HTTP
- MCP assistant → stdio transport: MCP over stdio
- Server bootstrap → HTTP transport: starts
src/index.ts - Server bootstrap → stdio transport: starts
src/index.ts - HTTP transport → OIDC and ACL: validates access
src/server/httpServer.ts - HTTP transport → Request context: sets request scope
src/lib/requestContext.ts - HTTP transport → Session connections: initializes sessions
src/server/httpServer.ts - HTTP transport → Tool dispatcher: dispatches tools
src/server/httpServer.ts - stdio transport → Tool dispatcher: dispatches tools
src/server/stdioServer.ts - Tool dispatcher → Tool registry: loads tools
src/actualToolsManager.ts - Tool registry → Budget operations: registers
src/tools/index.ts - Tool registry → Transaction operations: registers
src/tools/index.ts - Tool registry → Accounts and entities: registers
src/tools/index.ts - Tool registry → Queries and summaries: registers
src/tools/index.ts - Tool dispatcher → Actual API adapter: executes tool calls
- Queries and summaries → Query validation: validates queries
src/tools/query_run.ts - Query validation → Actual schema: checks schema
src/lib/query-validator.ts - Connection lifecycle → Actual Budget server: connects and loads budget
- Session connections → Connection lifecycle: manages sessions
src/lib/ActualConnectionPool.ts - Actual API adapter → Actual Budget server: queries and syncs
- Actual API adapter → Session connections: uses session pool
src/lib/actual-adapter.ts - Actual API adapter → Request context: reads request scope
src/lib/requestContext.ts - OIDC and ACL → Configuration: uses settings
src/auth/budget-acl-dynamic.ts - HTTP transport → Configuration: reads settings
src/server/httpServer.ts - Server bootstrap → Logging and observability: logs startup
src/index.ts