# Firecent MCP Server

MCP (Model Context Protocol) server for [Firecent](https://github.com/luisemaltez/firecent) — a personal finance app (Next.js 16 + Prisma 7 + PostgreSQL).

This server lets AI agents (like Hermes) read and manage financial data through Firecent's REST API:

- **Accounts** — list, get, create
- **Records** — list, get, create transactions (income, expense, transfer)
- **Categories** — list, get, create
- **Query** — flexible query endpoint
- **Info** — API key + permissions validation

## Architecture

Same pattern as [`iris-mcp`](https://github.com/lumir-labs/iris-mcp):

```
firecent-mcp/
├── mcp/
│   ├── index.ts              # HTTP entry point (port 3000)
│   ├── tools/                # MCP tool registrations
│   ├── services/             # API service classes
│   ├── schemas/              # Zod input schemas
│   └── utils/                # API client + response helpers
├── package.json
└── tsconfig.json
```

## Setup

```bash
bun install
```

## Environment variables

Create `.env`:

```env
API_URL=https://firecent.example.com
```

The API token is passed by the client via the `Authorization: Bearer <token>` header (or `x-api-key`).

## Run

```bash
# Development (watch mode)
bun run dev

# Production
bun run start
```

The server runs on port `3000` with:
- `GET /` — health check (HTML)
- `POST /mcp` — MCP protocol endpoint (requires `Authorization` header)

## Available tools

### Read tools
- `firecent_info` — validate API key + permissions
- `firecent_list_accounts` — list all accounts
- `firecent_get_account` — get account by ID
- `firecent_list_records` — list records (paginated)
- `firecent_get_record` — get record by ID
- `firecent_list_account_records` — list records for an account
- `firecent_list_categories` — list all categories
- `firecent_get_category` — get category by ID
- `firecent_query` — flexible query

### Write tools
- `firecent_create_record` — create transaction
- `firecent_create_account` — create account
- `firecent_create_category` — create category

## License

Private — Lumir Labs.