convez.ai
MCP ServerFinanceiroIntermediário
RadCod3

LamPyrid

RadCod3/LamPyrid

Automação de finanças pessoais via MCP para Firefly III

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP para integração com Firefly III, software de gestão financeira pessoal. Oferece 22 ferramentas para automação de fluxos financeiros, incluindo gerenciamento de contas, operações transacionais, orçamentos e análises. Funciona localmente ou remotamente via Docker.

Instalação

$npx convez-ai RadCod3/LamPyrid

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
24
Forks
5
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v0.5.0
Issues abertas
4
Contribuidores
4

Casos de uso

  • Automatizar reconciliação e criação de transações financeiras
  • Consultar saldos, extratos e orçamentos em tempo real
  • Integrar Firefly III com workflows de IA no Claude

Veredito

Ferramenta sólida e bem documentada para quem gerencia finanças pessoais com Firefly III e quer automação via Claude. Suporta deploy local e remoto, com bom coverage de operações financeiras. Recomendado para usuários técnicos que buscam integração profunda com infraestrutura de IA.

README

A tradução para o português deste README ainda está na fila.

LamPyrid

A Model Context Protocol (MCP) server providing comprehensive tools for interacting with Firefly III personal finance software. LamPyrid enables automated personal finance workflows and analysis through 22 MCP tools with support for account management, transaction operations, budget management, and financial insights.

What is Firefly III? Firefly III is a free and open-source personal finance manager that helps you track expenses, income, budgets, and more. LamPyrid provides an MCP interface to automate interactions with your Firefly III instance.

Features

  • Account Management: List, search, and retrieve account information across all Firefly III account types
  • Transaction Operations: Full CRUD operations for withdrawals, deposits, and transfers
  • Bulk Operations: Efficient bulk transaction creation and updates
  • Budget Management: Budget analysis with spending tracking and allocation
  • Docker Support: Production-ready multi-platform images (amd64/arm64)

Prerequisites

  • Access to a Firefly III instance with a Personal Access Token
  • For local installation: Python 3.14+ and uv
  • For Docker: Docker installed on your system

Adding to Claude

Option 1: Local Setup (Claude Desktop)

Clone and install LamPyrid:

git clone https://github.com/RadCod3/LamPyrid.git
cd LamPyrid
uv sync

Add to your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "lampyrid": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/LamPyrid", "lampyrid"],
      "env": {
        "FIREFLY_BASE_URL": "https://your-firefly-instance.com",
        "FIREFLY_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Restart Claude Desktop to enable LamPyrid tools.

Option 2: Remote Setup (Claude Connector)

When hosted on a remote server, LamPyrid can be added as a Claude Connector, allowing you to use it across all Claude interfaces including Claude mobile apps (iOS/Android), Claude web, and Claude Desktop.

1. Deploy LamPyrid to a remote server:

# docker-compose.yml
services:
  lampyrid:
    image: ghcr.io/radcod3/lampyrid:latest
    ports:
      - "3000:3000"
    env_file:
      - .env
    restart: unless-stopped
# .env
FIREFLY_BASE_URL=https://your-firefly-instance.com
FIREFLY_TOKEN=your-api-token
MCP_TRANSPORT=http
docker compose up -d

2. Add as Claude Connector:

  1. Go to Claude Settings > Connectors > Add connector
  2. Enter your server URL: https://your-server-url.com/mcp
  3. LamPyrid is now available on all your Claude devices!

Security Note: If hosting on a public server, it is strongly recommended to enable authentication. LamPyrid currently supports Google OAuth - see the Authentication section below.

Configuration

Required

VariableDescription
FIREFLY_BASE_URLURL of your Firefly III instance
FIREFLY_TOKENPersonal access token for API authentication

Server Options

VariableDefaultDescription
MCP_TRANSPORTstdioTransport protocol: stdio, http, or sse
MCP_HOST0.0.0.0Host binding for HTTP/SSE transports
MCP_PORT3000Port binding for HTTP/SSE transports
LOGGING_LEVELINFOLogging verbosity: DEBUG/INFO/WARNING/ERROR/CRITICAL

Authentication (Optional)

Recommended for remote deployments. Currently supports Google OAuth.

VariableDescription
GOOGLE_CLIENT_IDGoogle OAuth 2.0 client ID
GOOGLE_CLIENT_SECRETGoogle OAuth 2.0 client secret
SERVER_BASE_URLYour server's public URL (e.g., https://lampyrid.example.com)

Setting up Google OAuth:

  1. Go to Google Cloud Console
  2. Create or select a project
  3. Navigate to APIs & Services > OAuth consent screen and configure
  4. Go to Credentials > Create Credentials > OAuth client ID
  5. Application type: Web application
  6. Add authorized redirect URI: {SERVER_BASE_URL}/auth/callback
  7. Copy the Client ID and Client Secret to your environment

Token Persistence (Optional)

Enable persistent authentication across server restarts:

VariableDescription
JWT_SIGNING_KEYJWT signing key (generate: python -c "import secrets; print(secrets.token_urlsafe(32))")
OAUTH_STORAGE_ENCRYPTION_KEYFernet key (generate: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
OAUTH_STORAGE_PATHStorage path (default: /app/data/oauth for Docker)

Available Tools

Account Management (3 tools)

ToolDescription
list_accountsList accounts by type (asset, expense, revenue, etc.)
search_accountsSearch accounts by name with optional type filtering
get_accountGet detailed information for a single account

Transaction Management (10 tools)

ToolDescription
get_transactionsRetrieve transactions with time range and type filtering
search_transactionsSearch transactions by description or text fields
get_transactionGet detailed information for a single transaction
create_withdrawalCreate withdrawal transactions with budget allocation
create_depositCreate deposit transactions
create_transferCreate transfer transactions between accounts
create_bulk_transactionsCreate multiple transactions in a single operation
update_transactionUpdate existing transaction details
bulk_update_transactionsUpdate multiple transactions in a single operation
delete_transactionDelete transactions by ID

Budget Management (6 tools)

ToolDescription
list_budgetsList all budgets with optional filtering
get_budgetGet detailed budget information
get_budget_spendingAnalyze spending for specific budgets and periods
get_budget_summaryComprehensive summary of all budgets with spending
get_available_budgetCheck available budget amounts for periods
create_budgetCreate new budgets with auto-budget options

Docker

Available Images

TagDescription
latestLatest stable release (recommended)
edgeMain branch (latest features, may be unstable)
0.3.0, 0.3, 0Specific versions

All images support linux/amd64 and linux/arm64 platforms.

docker pull ghcr.io/radcod3/lampyrid:latest

Volume Permissions

If you encounter permission errors with OAuth storage, set the correct ownership:

mkdir -p ./data/oauth
sudo chown -R 65532:65532 ./data/oauth

Development

# Install dependencies
uv sync

# Format and lint
uv run ruff format
uv run ruff check --fix

# Run the server
uv run lampyrid

# Run tests
uv run pytest

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Make changes following the code style (run uv run ruff format && uv run ruff check --fix)
  4. Submit a pull request

License

GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE.

Support

For issues and feature requests, use the GitHub issue tracker.

Ver o original no GitHub

Bom para

Relacionados