README.md•4.64 kB
# Moneybird MCP Server
A Model Context Protocol (MCP) server that connects AI assistants like Claude to Moneybird accounting software via API.
## Features
- **Contact Management**: List, retrieve, filter, create, and update contacts
- Advanced filtering by creation date, update date, name, and more
- **Financial Data**: Access sales invoices, financial accounts, and payments
- **Business Operations**: Manage products, projects, and time entries
- **Custom Requests**: Make custom API requests to Moneybird endpoints
- **Interactive Assistant**: Preconfigured prompt for a Moneybird assistant
## New Developments
- **Enhanced Contact Filtering**: Filter contacts using Moneybird's advanced query syntax
- Filter by creation date: `created_after:2023-01-01 00:00:00 UTC`
- Filter by update date: `updated_after:2023-01-01 10:45:35 UTC`
- Filter by properties: `first_name:value`, etc.
- **Improved Error Handling**: Better error messages and recovery
- **Performance Optimizations**: Response chunking for large datasets
- **TypeScript Integration**: Full type safety with Zod schema validation
## Setup Instructions
### Basic Setup
1. **Install the package**:
```bash
npm install -g moneybird-mcp-server
```
2. **Create a .env file** with your Moneybird credentials:
```
MONEYBIRD_API_TOKEN=your_api_token
MONEYBIRD_ADMINISTRATION_ID=your_administration_id
```
3. **Run the server**:
```bash
npx moneybird-mcp-server
```
### Claude Desktop Setup
To set up this MCP server in Claude Desktop:
1. **Install the package globally** if you haven't already:
```bash
npm install -g moneybird-mcp-server
```
2. **Create or edit** the Claude Desktop configuration file (usually in `~/Library/Application
Support/Claude/claude_desktop_config.json`) to include the MCP server configuration:
```json
{
"mcpServers": {
"moneybird": {
"command": "npx",
"args": [
"-y",
"moneybird-mcp-server"
],
"env": {
"MONEYBIRD_API_TOKEN": "your_api_token_here",
"MONEYBIRD_ADMINISTRATION_ID": "your_administration_id_here"
}
}
}
}
```
3. **Restart Claude Desktop** to apply the changes
4. **Connect to the MCP server** by typing `/mcp moneybird` in the Claude chat input
## Usage Examples
### Basic Contact Listing
## Overview
This server allows AI assistants to interact with your Moneybird accounting data using the Model Context Protocol. It
provides various tools to:
- List and retrieve contacts
- View sales invoices
- Check financial accounts
- Access products and projects
- View time entries
- Make custom Moneybird API requests
## Prerequisites
- Node.js (v18 or higher recommended)
- A Moneybird account with API access
- A Moneybird API token
## Setup
1. Clone this repository:
```
git clone https://github.com/vanderheijden86/moneybird-mcp-server.git
cd moneybird-mcp-server
```
2. Install dependencies:
```
npm install
```
3. Create `.env` file from the example:
```
cp .env.example .env
```
4. Edit the `.env` file with your Moneybird API credentials:
- `MONEYBIRD_API_TOKEN`: Your Moneybird API token (generate at https://moneybird.com/user/applications)
- `MONEYBIRD_ADMINISTRATION_ID`: Your Moneybird administration ID (found in URL when logged in)
- `MCP_SERVER_PORT`: The port to run the MCP server on (default: 3000)
## Running the Server
For development:
```
npm run dev
```
For production:
```
npm run build
npm start
```
## Using with AI Assistants
This MCP server is compatible with any AI assistant that supports the Model Context Protocol. Once running, you can
connect it to your AI assistant by providing the server URL:
```
http://your-server-address:3000
```
## Available Tools
The server provides the following tools:
- `list_contacts`: List all contacts in Moneybird
- `get_contact`: Get details for a specific contact by ID
- `list_sales_invoices`: List all sales invoices
- `get_sales_invoice`: Get details for a specific sales invoice by ID
- `list_financial_accounts`: List all financial accounts
- `list_products`: List all products
- `list_projects`: List all projects
- `list_time_entries`: List all time entries
- `moneybird_request`: Make a custom request to the Moneybird API
## Security
This server should be deployed with appropriate security measures, as it provides access to your Moneybird data.
Consider:
- Running behind a secure proxy
- Implementing authentication for the MCP server
- Using HTTPS
- Restricting network access
## License
MIT