Skip to content

chore: update README.md for clarity and organization #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RadCod3 merged 1 commit into from
Jan 18, 2026
+41 −129
Merged

chore: update README.md for clarity and organization #65

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 41 additions & 129 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,76 +6,40 @@ A Model Context Protocol (MCP) server providing comprehensive tools for interact

## Features

- **Comprehensive Account Management**: List, search, and retrieve account information across all Firefly III account types
- **Transaction Operations**: Full CRUD operations for transactions with support for withdrawals, deposits, and transfers
- **Bulk Operations**: Efficient bulk transaction creation and updates for high-volume workflows
- **Budget Management**: Complete budget analysis with spending tracking, allocation, and summary reporting
- **Docker Support**: Production-ready Docker images with multi-platform support (amd64/arm64)
- **Type Safety**: Full type hints and Pydantic validation throughout the codebase
- **Async Operations**: Non-blocking HTTP operations for optimal performance
- **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)

## Quick Start

### Prerequisites
## Prerequisites

- Access to a Firefly III instance with a [Personal Access Token](https://docs.firefly-iii.org/how-to/firefly-iii/features/api/#personal-access-token)
- For local installation: Python 3.14+ and [uv](https://github.com/astral-sh/uv) package manager
- For local installation: Python 3.14+ and [uv](https://github.com/astral-sh/uv)
- For Docker: Docker installed on your system

### Option 1: Docker (Recommended)
## Adding to Claude

```bash
docker pull ghcr.io/radcod3/lampyrid:latest
```
### Option 1: Local Setup (Claude Desktop)

### Option 2: Local Installation
Clone and install LamPyrid:

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

## Adding to Claude

LamPyrid can be used with Claude in two ways:

### Local Setup (Claude Desktop)

For running LamPyrid locally on your machine with Claude Desktop.

**Using Docker:**

Add to your Claude Desktop configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
"mcpServers": {
"lampyrid": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "MCP_TRANSPORT=stdio",
"-e", "FIREFLY_BASE_URL=https://your-firefly-instance.com",
"-e", "FIREFLY_TOKEN=your-personal-access-token",
"ghcr.io/radcod3/lampyrid:latest"
]
}
}
}
```

**Using Local Installation:**

```json
{
"mcpServers": {
"lampyrid": {
"command": "uv",
"args": ["run", "lampyrid"],
"cwd": "/path/to/LamPyrid",
"args": ["run", "--project", "/path/to/LamPyrid", "lampyrid"],
"env": {
"FIREFLY_BASE_URL": "https://your-firefly-instance.com",
"FIREFLY_TOKEN": "your-personal-access-token"
Expand All @@ -85,9 +49,9 @@ Add to your Claude Desktop configuration file:
}
```

After adding the configuration, restart Claude Desktop. LamPyrid tools will be available for account management, transaction operations, and budget analysis.
Restart Claude Desktop to enable LamPyrid tools.

### Remote Setup (Claude Connector)
### 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.

Expand All @@ -100,26 +64,32 @@ services:
image: ghcr.io/radcod3/lampyrid:latest
ports:
- "3000:3000"
environment:
FIREFLY_BASE_URL: https://your-firefly-instance.com
FIREFLY_TOKEN: your-api-token
MCP_TRANSPORT: http
env_file:
- .env
restart: unless-stopped
```

```bash
# .env
FIREFLY_BASE_URL=https://your-firefly-instance.com
FIREFLY_TOKEN=your-api-token
MCP_TRANSPORT=http
```

```bash
docker compose up -d
```

**2. Add as Claude Connector:**

1. Go to [Claude Settings](https://claude.ai/settings/integrations)
2. Navigate to **Integrations** > **Add More**
3. Enter your server URL: `https://your-server-url.com`
4. LamPyrid is now available on all your Claude devices!
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 Setup](#google-oauth-authentication-optional) section for configuration.
> **Security Note**: If hosting on a public server, it is strongly recommended to enable authentication. LamPyrid currently supports Google OAuth - see the [Authentication](#authentication-optional) section below.

## Configuration

LamPyrid uses environment variables for configuration:

### Required

| Variable | Description |
Expand All @@ -136,9 +106,9 @@ LamPyrid uses environment variables for configuration:
| `MCP_PORT` | `3000` | Port binding for HTTP/SSE transports |
| `LOGGING_LEVEL` | `INFO` | Logging verbosity: DEBUG/INFO/WARNING/ERROR/CRITICAL |

### Google OAuth Authentication (Optional)
### Authentication (Optional)

Recommended for remote server deployments to secure access to your financial data. Currently, Google OAuth is the only supported authentication provider.
Recommended for remote deployments. Currently supports Google OAuth.

| Variable | Description |
|----------|-------------|
Expand All @@ -156,7 +126,7 @@ Recommended for remote server deployments to secure access to your financial dat
6. Add authorized redirect URI: `{SERVER_BASE_URL}/auth/callback`
7. Copy the Client ID and Client Secret to your environment

### OAuth Token Persistence (Optional)
### Token Persistence (Optional)

Enable persistent authentication across server restarts:

Expand All @@ -166,7 +136,7 @@ Enable persistent authentication across server restarts:
| `OAUTH_STORAGE_ENCRYPTION_KEY` | Fernet key (generate: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`) |
| `OAUTH_STORAGE_PATH` | Storage path (default: `/app/data/oauth` for Docker) |

## Available MCP Tools
## Available Tools

### Account Management (3 tools)
| Tool | Description |
Expand Down Expand Up @@ -198,7 +168,7 @@ Enable persistent authentication across server restarts:
| `get_budget_summary` | Comprehensive summary of all budgets with spending |
| `get_available_budget` | Check available budget amounts for periods |

## Docker Deployment
## Docker

### Available Images

Expand All @@ -210,53 +180,13 @@ Enable persistent authentication across server restarts:

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

### Using Docker Compose

The repository includes a `docker-compose.yml` for easy deployment:

```yaml
services:
lampyrid:
image: ghcr.io/radcod3/lampyrid:latest
ports:
- "3000:3000"
env_file:
- .env
volumes:
# Persist OAuth tokens across container restarts
- ./data/oauth:/app/data/oauth
restart: unless-stopped
```

Create a `.env` file with your configuration:

```bash
# Required
FIREFLY_BASE_URL=https://your-firefly-instance.com
FIREFLY_TOKEN=your-api-token

# Optional - Server settings
MCP_TRANSPORT=http
LOGGING_LEVEL=INFO

# Optional - For remote authentication
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
SERVER_BASE_URL=https://your-domain.com

# Optional - For persistent OAuth tokens
JWT_SIGNING_KEY=your-jwt-key
OAUTH_STORAGE_ENCRYPTION_KEY=your-encryption-key
OAUTH_STORAGE_PATH=/app/data/oauth
docker pull ghcr.io/radcod3/lampyrid:latest
```

Then start the server:

```bash
docker compose up -d
```
### Volume Permissions

**Note on Volume Permissions**: If you encounter permission errors with OAuth storage, set the correct ownership:
If you encounter permission errors with OAuth storage, set the correct ownership:

```bash
mkdir -p ./data/oauth
Expand All @@ -269,10 +199,8 @@ sudo chown -R 65532:65532 ./data/oauth
# Install dependencies
uv sync

# Format code
# Format and lint
uv run ruff format

# Lint code
uv run ruff check --fix

# Run the server
Expand All @@ -282,22 +210,6 @@ uv run lampyrid
uv run pytest
```

### Project Structure

```
LamPyrid/
├── src/lampyrid/
│ ├── server.py # FastMCP server initialization
│ ├── config.py # Environment configuration
│ ├── clients/firefly.py # HTTP client for Firefly III API
│ ├── models/ # Pydantic models
│ ├── services/ # Business logic layer
│ └── tools/ # MCP tool definitions
├── tests/ # Unit and integration tests
├── Dockerfile # Docker image definition
└── docker-compose.yml # Docker Compose configuration
```

## Contributing

Contributions are welcome! Please:
Expand All @@ -309,8 +221,8 @@ Contributions are welcome! Please:

## License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.
GNU Affero General Public License v3.0 (AGPL-3.0) - see [LICENSE](LICENSE).

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/RadCod3/LamPyrid/issues).
For issues and feature requests, use the [GitHub issue tracker](https://github.com/RadCod3/LamPyrid/issues).