Finmap MCP Server

MCP server for Finmap, a financial management platform. Work with accounts, operations, invoices, and reference data from any MCP-compatible client.

22 tools covering the full Finmap API v2.2.

Requirements

• Node.js 20+
• Finmap API key (Settings → API in your Finmap account)

Installation

git clone https://github.com/hlebtkachenko/finmap-mcp.git
cd finmap-mcp
npm ci
npm run build

Configuration

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "finmap": {
      "command": "node",
      "args": ["/path/to/finmap-mcp/dist/index.js"],
      "env": {
        "FINMAP_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json (location)

{
  "mcpServers": {
    "finmap": {
      "command": "node",
      "args": ["/path/to/finmap-mcp/dist/index.js"],
      "env": {
        "FINMAP_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

.mcp.json in your project root, or ~/.claude.json globally:

{
  "mcpServers": {
    "finmap": {
      "command": "node",
      "args": ["/path/to/finmap-mcp/dist/index.js"],
      "env": {
        "FINMAP_API_KEY": "your-api-key"
      }
    }
  }
}

Any MCP client (stdio)

The server uses stdio transport. Point your MCP client to:

node /path/to/finmap-mcp/dist/index.js

With the FINMAP_API_KEY environment variable set.

Environment Variables

Variable	Required	Description
FINMAP_API_KEY	Yes	API key from Finmap account settings

Tools

Accounts & Reference Data

Tool	Description
finmap_accounts	List all accounts with balances
finmap_categories_income	Income categories
finmap_categories_expense	Expense categories
finmap_projects	List projects
finmap_tags	List tags
finmap_currencies	Supported currencies
finmap_suppliers	Suppliers and counterparties
finmap_project_create	Create a project
finmap_tag_create	Create a tag

Operations

Tool	Description
finmap_operations_list	Search and filter by type, date, account, category, project, or tag
finmap_operation_detail	Get operation by ID or external ID
finmap_income_create	Create income operation
finmap_expense_create	Create expense operation
finmap_transfer_create	Create transfer between accounts
finmap_operation_delete	Delete an operation

Invoices

Tool	Description
finmap_invoices_list	List and filter by date, status, or confirmation
finmap_invoice_detail	Invoice details by ID
finmap_invoice_create	Create invoice with goods, company, and client details
finmap_invoice_delete	Delete an invoice
finmap_invoice_companies	List your company profiles
finmap_invoice_goods	Available goods and services

Raw API

Tool	Description
finmap_api_raw	Call any Finmap API v2.2 endpoint directly

Security

• 30-second timeout on all HTTP requests
• JSON body parsing wrapped in try/catch
• Amount fields validated as non-negative numbers
• Date parameters validated before conversion to timestamps
• Error responses truncated to 500 characters
• All parameters validated with Zod schemas

Architecture

src/
  index.ts              Entry point, env validation
  finmap-client.ts      API client (apiKey header auth)
  tools/
    reference.ts        Accounts and reference data (9 tools)
    operations.ts       Financial operations (6 tools)
    invoices.ts         Invoice management (7 tools)

Tech Stack

• TypeScript
• @modelcontextprotocol/sdk
• Zod (schema validation)
• Native fetch

API Reference

Finmap API v2.2

License

MIT