Lunchmoney Go Client & MCP Server
Cidan/lunchmoney-go
Cliente Go + MCP server para Lunch Money v2 com autenticação flexível
Ver no GitHubCliente Go idiomoático e servidor MCP para a API v2 do Lunch Money, gerado a partir da especificação OpenAPI oficial. Suporta múltiplos modos de autenticação (token estático, context, OAuth2 stateful e stateless) com validação de erro tipado.
Instalação
npx convez-ai Cidan/lunchmoney-go1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar gestão financeira pessoal em aplicações Go
- Expor operações do Lunch Money como ferramentas MCP para Claude
- Consultar transações e dados financeiros programaticamente
- Construir sistemas multi-tenant com autenticação OAuth2 stateless
Veredito

Implementação sólida de cliente Go com geração de código a partir de OpenAPI e suporte robusto a múltiplos padrões de autenticação. MCP server pronto para uso, embora OAuth2 ainda esteja em estágio de placeholder — adequado para projetos que usem tokens estáticos ou context-based.
README
A tradução para o português deste README ainda está na fila.
lunchmoney-go
Go client and MCP server for the Lunch Money v2 API.
- Library: import
github.com/Cidan/lunchmoney-goto talk to the v2 API. - MCP server:
go install github.com/Cidan/lunchmoney-go/cmd/lunchmoney-mcp@latestexposes the API as MCP tools over stdio or Streamable HTTP.
The library exposes idiomatic Go method signatures backed by DTOs generated from the official OpenAPI spec via oapi-codegen.
Auth modes
The client picks exactly one auth mode at construction time. Modes are mutually exclusive — there is no precedence and no fallback. Each call validates the request context against the configured mode and returns a typed error on mismatch.
| Mode | Constructor option | Required ctx values | Forbidden ctx values |
|---|---|---|---|
| Static | WithStaticToken(s) | — | auth.Token, auth.TokenID |
| Context | WithContextAuth() | auth.Token | auth.TokenID |
| OAuth2 stateful | WithTokenSource(src) | — | auth.Token, auth.TokenID |
| OAuth2 stateless | WithTokenStore(cfg, store) | auth.TokenID | auth.Token |
Errors:
ErrNoAuthMode—NewClientcalled with no auth optionErrConflictingAuthModes—NewClientcalled with more than one auth optionErrAuthModeMismatch— context carries values inconsistent with the configured modeErrMissingContextToken— ContextAuth client was called withoutauth.WithTokenErrMissingContextTokenID— TokenStore client was called withoutauth.WithTokenIDErrOAuth2NotImplemented— placeholder for the OAuth2 stub (see below)
All errors support errors.Is.
Mode 1: static token
c, _ := lunchmoney.NewClient(lunchmoney.WithStaticToken(os.Getenv("LM_TOKEN")))
me, err := c.Me.Get(ctx)
Mode 2: token from context.Context
import (
lunchmoney "github.com/Cidan/lunchmoney-go"
"github.com/Cidan/lunchmoney-go/auth"
)
c, _ := lunchmoney.NewClient(lunchmoney.WithContextAuth())
ctx = auth.WithToken(ctx, req.Header.Get("X-LM-Token"))
txns, err := c.Transactions.List(ctx, nil)
The same client instance can serve many tenants concurrently — the token is read from ctx per request.
Mode 3: OAuth2 stateful (one client == one token)
import "github.com/Cidan/lunchmoney-go/oauth2lm"
cfg := &oauth2lm.Config{
ClientID: "abc",
ClientSecret: "shh",
RedirectURL: "https://app.example.com/cb",
Scopes: []string{"read", "write"},
}
src := cfg.TokenSource(ctx, &oauth2lm.Token{AccessToken: "..."})
c, _ := lunchmoney.NewClient(lunchmoney.WithTokenSource(src))
Mode 4: OAuth2 stateless (TokenStore + ID from context)
type pgStore struct{ db *sql.DB }
func (s *pgStore) Get(ctx context.Context, id string) (*oauth2lm.Token, error) { /* ... */ }
func (s *pgStore) Put(ctx context.Context, id string, t *oauth2lm.Token) error { /* ... */ } // refresh writeback
cfg := &oauth2lm.Config{ /* ... */ }
c, _ := lunchmoney.NewClient(lunchmoney.WithTokenStore(cfg, &pgStore{db: db}))
ctx = auth.WithTokenID(ctx, currentUserID)
txns, err := c.Transactions.List(ctx, nil)
OAuth2 status
OAuth2 is stubbed. The oauth2lm package exists with the full type and interface surface so callers can wire OAuth2-mode clients today, but the operational helpers (Config.Exchange, TokenSource.Token, Config.AuthCodeURL) all return ErrOAuth2NotImplemented. The wiring through the lunchmoney client itself (mode validation, ctx checks, store fetch / source call) is real and exercised by the test suite — only the credential-issuing/refreshing logic is missing.
Resources
Services on the client (Stripe-style):
c.Mec.Summaryc.Categories—List,Get,Create,Update,Deletec.ManualAccounts—List,Get,Create,Update,Deletec.PlaidAccounts—List,Get,Fetchc.Transactions—List,Get,Create,UpdateTransaction,BulkUpdate,Delete,BulkDelete,Group,Ungroup,Split,Unsplit,AttachFile,AttachmentURL,DeleteAttachmentc.Tags—List,Get,Create,Update,Deletec.RecurringItems—List,Getc.Budgets—Settings,Upsert,Delete
Use lunchmoney.MockBaseURL (or the convenience WithMockServer() option) to point at the static mock server, which accepts any bearer token of ≥11 characters.
MCP server
# stdio (default; for desktop MCP clients)
LUNCHMONEY_TOKEN=lm_... lunchmoney-mcp
# explicit token
lunchmoney-mcp --token lm_...
# Streamable HTTP, one shared static token
lunchmoney-mcp --transport http --addr :8080 --token lm_...
# Streamable HTTP, per-request token from a header
lunchmoney-mcp --transport http --addr :8080 --auth header:X-LM-Token
# Run against the static mock server (for local dev)
lunchmoney-mcp --transport stdio --token TESTTOKEN1234 --base-url mock
Tools registered on the server — 100% v2 endpoint coverage (every read + write endpoint in docs/lunchmoney.json has a matching MCP tool):
lm_me_get,lm_summary_get- Categories —
lm_categories_list,lm_categories_get,lm_categories_create,lm_categories_update,lm_categories_delete - Manual accounts —
lm_manual_accounts_list,lm_manual_accounts_get,lm_manual_accounts_create,lm_manual_accounts_update,lm_manual_accounts_delete - Plaid accounts —
lm_plaid_accounts_list,lm_plaid_accounts_get,lm_plaid_accounts_fetch - Tags —
lm_tags_list,lm_tags_get,lm_tags_create,lm_tags_update,lm_tags_delete - Recurring —
lm_recurring_list,lm_recurring_get - Budgets —
lm_budgets_settings_get,lm_budgets_upsert,lm_budgets_delete - Transactions —
lm_transactions_list,lm_transactions_get,lm_transactions_create,lm_transactions_update,lm_transactions_delete,lm_transactions_bulk_update,lm_transactions_bulk_delete,lm_transactions_group,lm_transactions_ungroup,lm_transactions_split,lm_transactions_unsplit,lm_transactions_attachment_upload,lm_transactions_attachment_url,lm_transactions_attachment_delete
Write tools that target endpoints with oneOf-encoded request fields (manual account balance, budget / transaction amount, split child amount) accept a free-form body map and route through Client.RawJSON; the resulting payload still goes through the auth-mode validation in Client.do. Tools whose body is fully typed (delete with options, bulk delete, plaid fetch, attachment URL/delete, ungroup/unsplit) call the corresponding typed method on the client.
The attachment upload tool (lm_transactions_attachment_upload) accepts the file as a base64-encoded content_b64 string plus file_name and content_type; the server decodes and forwards as multipart/form-data.
Code generation
Generated DTOs live in internal/lmtypes and are produced from docs/lunchmoney.json by oapi-codegen, pinned via the Go 1.24+ tool directive in go.mod.
To regenerate:
go generate ./...
The public surface in the root package re-exports the DTOs callers need (e.g. lunchmoney.Transaction, lunchmoney.Category); the generated package itself is private and not importable from outside the module.
Testing
# Unit tests + MCP smoke tests (no network)
go test ./...
# Read-only integration tests against the live mock server
go test -tags=integration ./...
# Full CRUD integration tests (slower; mock has a per-token rate limit)
go test -tags=integration_crud -p 1 ./...
The integration suite uses bearer token TESTTOKEN1234 (any ≥11-character string works against the mock at https://mock.lunchmoney.dev/v2). The integration_crud suite adds Create / Update / Delete coverage that validates request payload shapes against the mock's OpenAPI validator. It's gated separately because the mock enforces a token-bucket rate limit (~10 reqs / 40s) and the CRUD suite issues enough calls to flake under contention; running it on its own with -p 1 keeps it reliable.
Note: a few typed Create methods (
ManualAccounts.Create,Transactions.Create,Budgets.Upsert) include fields whose schema usesoneOf—oapi-codegenwraps these in a struct with a private union, so they can't be populated from the public surface. For now, route those creates throughClient.RawJSON(the integration suite demonstrates this); a future pass can add ergonomic constructor helpers.
License
Apache 2.0 (matches the upstream OpenAPI spec).