jfeilberg/bifrost-mcp

Bifrost MCP

MCP (Model Context Protocol) server for KarbonHQ accounting practice management API. Built with Next.js and deployable on Vercel.

Features

• Streamable HTTP Transport - Compatible with Vercel serverless deployment
• Full Karbon API Coverage - Tools for Client Groups, Contacts, Invoices, Payments, Business Cards, Comments, and Integration Tasks
• OData Support - Full support for filtering, sorting, and pagination

Available MCP Tools

Client Groups

• list_client_groups - List client groups with OData filtering
• get_client_group - Get a client group by key
• get_client_group_by_identifier - Get client group by user-defined identifier
• create_client_group - Create a new client group
• update_client_group - Update an existing client group

Contacts

• list_contacts - List contacts with filtering by name, email, phone

Business Cards

• get_business_card - Get a business card by key
• update_business_card - Update business card information

Invoices

• list_invoices - List invoices with filtering and sorting
• get_invoice - Get invoice details

Payments

• list_payments - List payments
• get_payment - Get payment details
• create_manual_payment - Record a manual payment
• delete_manual_payment - Delete a manual payment
• reverse_manual_payment - Reverse a manual payment

Comments

• get_comment - Get a comment by key

Integration Tasks

• list_integration_task_definitions - List available task definitions
• list_integration_tasks - List integration tasks
• get_integration_task - Get task details
• update_integration_task - Update task status/data

Setup

1. Clone and Install

git clone <repository-url>
cd bifrost-mcp
pnpm install

2. Configure Environment

Copy the example environment file:

cp .env.example .env.local

Add your Karbon API credentials to .env.local:

KARBON_BEARER_TOKEN=your_bearer_token_here
KARBON_ACCESS_KEY=your_access_key_here

Getting your credentials:

• Bearer Token: Register at Karbon Developer Portal
• Access Key: Found in Karbon Settings → Connected Apps

3. Run Development Server

pnpm dev

The MCP endpoint will be available at http://localhost:3000/mcp

Deployment

Vercel

1. Push to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard:
   • KARBON_BEARER_TOKEN
   • KARBON_ACCESS_KEY
4. Deploy

The MCP endpoint will be at https://your-domain.vercel.app/mcp

Using with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "karbon": {
      "url": "https://your-domain.vercel.app/mcp"
    }
  }
}

For local development:

{
  "mcpServers": {
    "karbon": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OData Query Examples

The Karbon API uses OData for filtering and sorting. Examples:

# Filter by status
$filter=ClientGroupStatus eq 'Current'

# Filter by name contains
$filter=contains(FullName, 'Smith')

# Order by date descending
$orderby=InvoiceDate desc

# Pagination
$skip=10&$top=20

Project Structure

bifrost-mcp/
├── app/
│   ├── mcp/
│   │   └── route.ts      # MCP endpoint handler
│   ├── api/              # Future API routes
│   ├── layout.tsx
│   └── page.tsx
├── lib/
│   ├── karbon/
│   │   └── client.ts     # Karbon API client
│   └── mcp/
│       ├── server.ts     # MCP server setup
│       └── tools.ts      # Tool definitions & handlers
├── types/
│   └── karbon.ts         # TypeScript types
└── package.json

License

ISC