bokio-mcp

klowdo/bokio-mcp

3.1

If you are the rightful owner of bokio-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Bokio MCP Server is designed to integrate Bokio's accounting capabilities with AI assistants, providing a seamless and secure way to manage accounting tasks.

Tools
21
Resources
0
Prompts
0

🧾 Bokio MCP Server

Because your AI assistant shouldn't need an accounting degree to manage your books

A Model Context Protocol (MCP) server that brings the power of Bokio accounting to AI assistants. Built with Go, OAuth2, and a sprinkle of Nordic efficiency.

✨ Features

🔐 Secure OAuth2 Authentication

Full OAuth2 flow implementation with token management and automatic refresh

📊 Complete Bokio API Coverage

  • Invoices - Create, list, update, and manage sales invoices
  • Customers - Full CRUD operations for customer management
  • Journal Entries - Accounting journal operations with reversal support
  • File Uploads - Document and attachment management
  • Authentication - Secure connection management and status checking

🛡️ Read-Only Mode

Enable BOKIO_READ_ONLY=true to prevent all write operations while maintaining full read access - perfect for AI assistants that should observe but not modify.

🚀 Production Ready

  • Structured logging with slog
  • Graceful shutdown handling
  • Rate limiting and retry logic
  • Comprehensive error handling
  • Type-safe API with generated OpenAPI types

🎯 Quick Start

Installation Options

Using Nix (Recommended)
# Enter development environment
nix develop

# Or with direnv
direnv allow
Using Docker
docker run -it \
  -e BOKIO_CLIENT_ID=your_client_id \
  -e BOKIO_CLIENT_SECRET=your_client_secret \
  ghcr.io/klowdo/bokio-mcp:latest
From Source
# Clone the repository
git clone https://github.com/klowdo/bokio-mcp.git
cd bokio-mcp

# Build the server
make build

# Run the server
./bin/bokio-mcp

🔧 Configuration

Configure the server using environment variables:

# Required - OAuth2 credentials
export BOKIO_CLIENT_ID="your_client_id"
export BOKIO_CLIENT_SECRET="your_client_secret"

# Optional - API configuration
export BOKIO_BASE_URL="https://api.bokio.se"      # Default
export BOKIO_REDIRECT_URL="http://localhost:8080/callback"  # Default

# Optional - Security
export BOKIO_READ_ONLY="true"  # Enable read-only mode

Example .env file

BOKIO_CLIENT_ID=your_client_id_here
BOKIO_CLIENT_SECRET=your_client_secret_here
BOKIO_READ_ONLY=false

📚 Available MCP Tools

Authentication Tools

  • bokio_authenticate - Start OAuth2 authentication flow
  • bokio_exchange_token - Exchange authorization code for access token
  • bokio_get_connections - Get current connection information
  • bokio_check_auth - Check authentication status

Invoice Tools

  • bokio_list_invoices - List invoices with filtering and pagination
  • bokio_get_invoice - Get specific invoice details
  • bokio_create_invoice - Create new sales invoice
  • bokio_update_invoice - Update existing invoice

Customer Tools

  • bokio_list_customers - List customers with pagination
  • bokio_get_customer - Get specific customer details
  • bokio_create_customer - Create new customer
  • bokio_update_customer - Update customer information

Journal Tools

  • bokio_list_journal_entries - List journal entries
  • bokio_create_journal_entry - Create new journal entry
  • bokio_reverse_journal_entry - Reverse an existing entry
  • bokio_get_journal_entry - Get specific journal entry

Upload Tools

  • bokio_upload_file - Upload documents and attachments
  • bokio_list_uploads - List uploaded files
  • bokio_get_upload - Get upload metadata
  • bokio_download_file - Download uploaded file
  • bokio_delete_upload - Delete uploaded file

🎮 MCP Usage Examples

Claude Desktop Configuration

Add the Bokio MCP server to your Claude Desktop configuration file (claude_desktop_config.json):

Using Nix (Recommended)
{
  "mcpServers": {
    "bokio": {
      "command": "nix",
      "args": ["run", "github:klowdo/bokio-mcp", "--"],
      "env": {
        "BOKIO_CLIENT_ID": "your_client_id",
        "BOKIO_CLIENT_SECRET": "your_client_secret",
        "BOKIO_READ_ONLY": "false"
      }
    }
  }
}
Using Docker
{
  "mcpServers": {
    "bokio": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BOKIO_CLIENT_ID=your_client_id",
        "-e",
        "BOKIO_CLIENT_SECRET=your_client_secret",
        "-e",
        "BOKIO_READ_ONLY=false",
        "ghcr.io/klowdo/bokio-mcp:latest"
      ]
    }
  }
}
Using Local Binary
{
  "mcpServers": {
    "bokio": {
      "command": "/path/to/bokio-mcp",
      "env": {
        "BOKIO_CLIENT_ID": "your_client_id",
        "BOKIO_CLIENT_SECRET": "your_client_secret",
        "BOKIO_READ_ONLY": "false"
      }
    }
  }
}

Command Line Usage

Running with Nix
# Run directly from GitHub
nix run github:klowdo/bokio-mcp

# Or if you've cloned the repository
cd bokio-mcp
nix run .
Running with Docker
# Pull and run the latest image
docker run -it \
  -e BOKIO_CLIENT_ID=your_client_id \
  -e BOKIO_CLIENT_SECRET=your_client_secret \
  -e BOKIO_READ_ONLY=false \
  ghcr.io/klowdo/bokio-mcp:latest

# Or with environment file
docker run -it --env-file .env ghcr.io/klowdo/bokio-mcp:latest
Running from Source
# Build and run
make build
BOKIO_CLIENT_ID=your_id BOKIO_CLIENT_SECRET=your_secret ./bin/bokio-mcp

# Or use the development target
make dev

Example Usage Scenarios

Once configured with your MCP client (like Claude Desktop), you can interact with Bokio using natural language:

Authentication Flow
"Please authenticate with Bokio and show me the connection status"

The assistant will use bokio_authenticate to start OAuth2 flow and bokio_check_auth to verify connection.

Invoice Management
"Create an invoice for customer ID 123 with a line item for consulting services, 1000 SEK"

The assistant will use bokio_create_invoice with the appropriate parameters.

"Show me all unpaid invoices from this month"

The assistant will use bokio_list_invoices with filtering parameters.

Customer Operations
"List all customers and show me details for any that have 'AB' in their name"

The assistant will use bokio_list_customers and bokio_get_customer as needed.

Journal Entries
"Create a journal entry for office supplies purchase, 500 SEK"

The assistant will use bokio_create_journal_entry with proper accounting codes.

File Management
"Upload this receipt file and attach it to invoice #12345"

The assistant will use bokio_upload_file and appropriate invoice update tools.

Read-Only Mode

For safe exploration and analysis, enable read-only mode:

{
  "mcpServers": {
    "bokio": {
      "command": "nix",
      "args": ["run", "github:klowdo/bokio-mcp", "--"],
      "env": {
        "BOKIO_CLIENT_ID": "your_client_id",
        "BOKIO_CLIENT_SECRET": "your_client_secret",
        "BOKIO_READ_ONLY": "true"
      }
    }
  }
}

In read-only mode, all write operations (create_*, update_*, delete_*) are disabled, but you can still:

  • List and view invoices, customers, and journal entries
  • Check authentication status
  • Download and view uploaded files
  • Generate reports and analysis

🛠️ Development

Prerequisites

  • Go 1.23+
  • Make
  • Git

Development Commands

# Update OpenAPI schemas
make update-schema

# Generate types from schemas
make generate-types

# Run tests
make test

# Run linting
make lint

# Run development server with hot reload
make dev

# Run security scans
make security

# Clean build artifacts
make clean

# See all available commands
make help

Project Structure

bokio-mcp/
├── main.go              # Entry point and server setup
├── bokio/
│   ├── client.go        # Bokio API client with OAuth2
│   └── types.go         # API type definitions
├── tools/
│   ├── auth.go          # Authentication tools
│   ├── invoices.go      # Invoice management tools
│   ├── customers.go     # Customer management tools
│   ├── journal.go       # Journal entry tools
│   └── uploads.go       # File upload tools
├── schemas/             # OpenAPI specifications
├── Makefile            # Development automation
└── flake.nix           # Nix development environment

🧪 Testing

The server includes comprehensive test coverage:

# Run all tests
make test

# Run with race detection
go test -race ./...

# Generate coverage report
make test
open coverage.html

🚢 Deployment

Docker Deployment

FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o bokio-mcp .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
COPY --from=builder /app/bokio-mcp /bokio-mcp
ENTRYPOINT ["/bokio-mcp"]

Systemd Service

[Unit]
Description=Bokio MCP Server
After=network.target

[Service]
Type=simple
User=bokio
ExecStart=/usr/local/bin/bokio-mcp
Restart=always
EnvironmentFile=/etc/bokio-mcp/env

[Install]
WantedBy=multi-user.target

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

  • Bokio for their excellent accounting API
  • Anthropic for the Model Context Protocol specification
  • The Go community for excellent OAuth2 and HTTP libraries

🔗 Links

Built with ❤️ and ☕ by klowdo