convez.ai
MCP ServerIntegração & APIsIntermediário
Cidan

Lunchmoney Go Client & MCP Server

Cidan/lunchmoney-go

Cliente Go + MCP server para Lunch Money v2 com autenticação flexível

Ver no GitHub
InicialPluginScore · de 0 a 100

Cliente 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-go

1 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

Estrelas
3
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

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-go to talk to the v2 API.
  • MCP server: go install github.com/Cidan/lunchmoney-go/cmd/lunchmoney-mcp@latest exposes 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.

ModeConstructor optionRequired ctx valuesForbidden ctx values
StaticWithStaticToken(s)—auth.Token, auth.TokenID
ContextWithContextAuth()auth.Tokenauth.TokenID
OAuth2 statefulWithTokenSource(src)—auth.Token, auth.TokenID
OAuth2 statelessWithTokenStore(cfg, store)auth.TokenIDauth.Token

Errors:

  • ErrNoAuthMode — NewClient called with no auth option
  • ErrConflictingAuthModes — NewClient called with more than one auth option
  • ErrAuthModeMismatch — context carries values inconsistent with the configured mode
  • ErrMissingContextToken — ContextAuth client was called without auth.WithToken
  • ErrMissingContextTokenID — TokenStore client was called without auth.WithTokenID
  • ErrOAuth2NotImplemented — 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.Me
  • c.Summary
  • c.Categories — List, Get, Create, Update, Delete
  • c.ManualAccounts — List, Get, Create, Update, Delete
  • c.PlaidAccounts — List, Get, Fetch
  • c.Transactions — List, Get, Create, UpdateTransaction, BulkUpdate, Delete, BulkDelete, Group, Ungroup, Split, Unsplit, AttachFile, AttachmentURL, DeleteAttachment
  • c.Tags — List, Get, Create, Update, Delete
  • c.RecurringItems — List, Get
  • c.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 uses oneOf — oapi-codegen wraps these in a struct with a private union, so they can't be populated from the public surface. For now, route those creates through Client.RawJSON (the integration suite demonstrates this); a future pass can add ergonomic constructor helpers.

License

Apache 2.0 (matches the upstream OpenAPI spec).

Ver o original no GitHub

Bom para

Relacionados