使用说明

FreshBooks MCP服务器

⚠️ 对于AI代理： 此存储库包括 OI.md 该文件包含专门为在OI OS（Brain Trust 4）环境中安装此服务器的AI代理设计的全面安装和配置说明。请参考 OI.md 有关分步设置说明、意图映射、参数规则和故障排除指南。

Freshbooks Mcp服务器

用于将FreshBooks与GenAI应用程序集成的模型上下文协议（MCP）服务器。

概述

小型企业会计软件

特性

全面的FreshBooks API覆盖范围
多种身份验证方法
企业已做好限速准备
完整的错误处理和重试逻辑
异步支持以获得更好的性能

先决条件

Python 3.8或更高版本
pip（Python包管理器）
具有API访问权限的FreshBooks帐户

安装

从源代码安装

克隆此存储库：

git clone https://github.com/OI-OS/freshbooks-mcp-server.git
cd freshbooks-mcp-server

安装依赖项：

pip install -e .

或者直接安装依赖项：

pip install httpx pydantic pydantic-settings python-dotenv mcp

复制 .env.example 到 .env:

cp .env.example .env

在中配置您的FreshBooks凭据 .env:
- FRESHBOOKS_API_TOKEN -您的FreshBooks API令牌（用于简单身份验证）
- FRESHBOOKS_BUSINESS_ID -您的FreshBooks业务ID（用于简单身份验证）
- FRESHBOOKS_CLIENT_ID -您的OAuth客户端ID（用于OAuth身份验证）
- FRESHBOOKS_CLIENT_SECRET -您的OAuth客户端密钥（用于OAuth身份验证）

注：永远不要承诺你的 .env 文件或令牌文件到版本控制。他们已经被排除在外了 .gitignore.

AI安装指南（OI OS/Brain Trust 4）

本节为AI助手提供了在OI OS环境中安装和配置FreshBooks MCP服务器的分步说明。

步骤1：通过OI命令安装

./oi install https://github.com/OI-OS/freshbooks-mcp-server.git

安装将：

将存储库克隆到 MCP-servers/freshbooks-mcp-server/
安装Python依赖项
自动检测服务器类型

步骤2：构建和安装依赖关系

cd MCP-servers/freshbooks-mcp-server
pip3 install -e .

步骤3：配置OAuth凭据

将以下内容添加到项目根目录 .env 文件：

# FreshBooks OAuth Configuration
FRESHBOOKS_CLIENT_ID=your_client_id_here
FRESHBOOKS_CLIENT_SECRET=your_client_secret_here
FRESHBOOKS_REDIRECT_URI=https://localhost:8080/callback

# FreshBooks Account Information (obtained after authentication)
FRESHBOOKS_ACCOUNT_ID=your_account_id_here
FRESHBOOKS_BUSINESS_ID=your_business_id_here
FRESHBOOKS_BUSINESS_NAME=your_business_name
FRESHBOOKS_USER_EMAIL=your_email@example.com
FRESHBOOKS_USER_NAME=Your Name

步骤4：连接服务器

连接OAuth服务器变体：

export FRESHBOOKS_CLIENT_ID=your_client_id_here
export FRESHBOOKS_CLIENT_SECRET=your_client_secret_here
export FRESHBOOKS_REDIRECT_URI=https://localhost:8080/callback

./brain-trust4 connect freshbooks-mcp-server python3 ./MCP-servers/freshbooks-mcp-server/src/freshbooks_mcp/simple_oauth_server.py

步骤5：身份验证（第一次）

OAuth流程需要手动与浏览器交互。两种方法：

方法A：自动身份验证（交互式）

./brain-trust4 call freshbooks-mcp-server authenticate '{}'

这将：

打开浏览器进行OAuth授权
等待用户完成授权
访问令牌的交换授权码
将令牌保存到 ~/.freshbooks_token

注：如果以非交互方式运行，此命令可能会超时。使用方法B进行自动化。

方法B：手动令牌交换

获取授权URL:

# Manually construct or trigger OAuth URL
# URL format: https://auth.freshbooks.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://localhost:8080/callback

用户在浏览器中完成授权 并接收授权码

访问令牌的交换代码：

export FRESHBOOKS_CLIENT_ID=your_client_id_here
export FRESHBOOKS_CLIENT_SECRET=your_client_secret_here
export FRESHBOOKS_REDIRECT_URI=https://localhost:8080/callback

python3 -c "
import asyncio
import httpx
import json
import os
import time

async def exchange_code():
    client_id = os.getenv('FRESHBOOKS_CLIENT_ID')
    client_secret = os.getenv('FRESHBOOKS_CLIENT_SECRET')
    redirect_uri = os.getenv('FRESHBOOKS_REDIRECT_URI')
    auth_code = 'AUTHORIZATION_CODE_FROM_USER'  # Replace with actual code
    
    async with httpx.AsyncClient() as client:
        response = await client.post(
            'https://api.freshbooks.com/auth/oauth/token',
            data={
                'grant_type': 'authorization_code',
                'client_id': client_id,
                'client_secret': client_secret,
                'redirect_uri': redirect_uri,
                'code': auth_code
            },
            headers={'Content-Type': 'application/x-www-form-urlencoded'}
        )
        result = response.json()
        print('Access Token:', result['access_token'])
        print('Account ID:', result['account_id'])
        print('Business ID:', result['business_id'])
        return result

result = asyncio.run(exchange_code())
"

将令牌保存到 ~/.freshbooks_token:

python3 -c "
import json
import time
import os

token_data = {
    'access_token': 'ACCESS_TOKEN_FROM_STEP_3',
    'account_id': 'ACCOUNT_ID_FROM_STEP_3',
    'business_id': 'BUSINESS_ID_FROM_STEP_3',
    'timestamp': time.time()
}

token_file = os.path.expanduser('~/.freshbooks_token')
with open(token_file, 'w') as f:
    json.dump(token_data, f)

print('✅ Token saved to', token_file)
"

可选：另存为FRESHBOOKS_API_TOKEN

OAuth访问令牌也可以用作 FRESHBOOKS_API_TOKEN 对于标准服务器。添加到 .env:
```
FRESHBOOKS_API_TOKEN=your_oauth_access_token_here
FRESHBOOKS_BUSINESS_ID=your_business_id_here
```
重要提示： OAuth令牌将在约12小时后过期。OAuth服务器自动处理令牌刷新，而标准服务器将需要手动更新令牌。

步骤6：验证安装

测试连接：

./oi "get freshbooks clients"

或者直接：

./brain-trust4 call freshbooks-mcp-server get_clients '{}'

AI安装故障排除

“未通过身份验证”错误：运行身份验证流（步骤5）
令牌已过期：重新验证或使用自动刷新的OAuth服务器
找不到环境变量：在连接服务器之前导出它们，或添加到 .env 并获取它
未找到模块：确保 pip3 install -e . 在服务器目录中成功完成

快速参考命令

# Install
./oi install https://github.com/OI-OS/freshbooks-mcp-server.git

# Connect OAuth server
export FRESHBOOKS_CLIENT_ID=... FRESHBOOKS_CLIENT_SECRET=... FRESHBOOKS_REDIRECT_URI=...
./brain-trust4 connect freshbooks-mcp-server python3 ./MCP-servers/freshbooks-mcp-server/src/freshbooks_mcp/simple_oauth_server.py

# Connect standard server (if you have API token)
./brain-trust4 connect freshbooks-api python3 ./MCP-servers/freshbooks-mcp-server/src/freshbooks_mcp/server.py

# Test
./oi "get freshbooks clients"

AI客户端的配置

与光标一起使用

打开光标设置
导航至特性 → 模型上下文协议
点击 编辑配置 或手动编辑MCP设置文件：
- macOS/Linux: ~/.cursor/mcp.json 或项目级别 .cursor/mcp.json
- 视窗: %APPDATA%\Cursor\mcp.json 或项目级别 .cursor\mcp.json
添加FreshBooks MCP服务器配置：

{
  "mcpServers": {
    "freshbooks": {
      "command": "python3",
      "args": ["/absolute/path/to/freshbooks-mcp-server/src/freshbooks_mcp/server.py"],
      "env": {
        "FRESHBOOKS_API_TOKEN": "your_freshbooks_api_token_here",
        "FRESHBOOKS_BUSINESS_ID": "your_business_id_here"
      }
    }
  }
}

用于OAuth身份验证，使用：

{
  "mcpServers": {
    "freshbooks-oauth": {
      "command": "python3",
      "args": ["/absolute/path/to/freshbooks-mcp-server/src/freshbooks_mcp/simple_oauth_server.py"],
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your_oauth_client_id_here",
        "FRESHBOOKS_CLIENT_SECRET": "your_oauth_client_secret_here"
      }
    }
  }
}

替代方案：使用项目级配置

创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "freshbooks": {
      "command": "python3",
      "args": ["./MCP-servers/freshbooks-mcp-server/src/freshbooks_mcp/server.py"],
      "env": {
        "FRESHBOOKS_API_TOKEN": "${FRESHBOOKS_API_TOKEN}",
        "FRESHBOOKS_BUSINESS_ID": "${FRESHBOOKS_BUSINESS_ID}"
      }
    }
  }
}

重新启动Cursor以应用更改

与Claude Desktop一起使用

找到您的Claude Desktop配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json
编辑配置文件并添加：

{
  "mcpServers": {
    "freshbooks": {
      "command": "python3",
      "args": ["/absolute/path/to/freshbooks-mcp-server/src/freshbooks_mcp/server.py"],
      "env": {
        "FRESHBOOKS_API_TOKEN": "your_freshbooks_api_token_here",
        "FRESHBOOKS_BUSINESS_ID": "your_business_id_here"
      }
    }
  }
}

保存文件并重新启动Claude Desktop

与VS代码（带MCP扩展）一起使用

为VS Code安装MCP扩展（如果可用）
创建或编辑 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "freshbooks": {
      "command": "python3",
      "args": ["/absolute/path/to/freshbooks-mcp-server/src/freshbooks_mcp/server.py"],
      "env": {
        "FRESHBOOKS_API_TOKEN": "your_freshbooks_api_token_here",
        "FRESHBOOKS_BUSINESS_ID": "your_business_id_here"
      },
      "type": "stdio"
    }
  }
}

与Continue.dev一起使用

打开Continue.dev配置文件：
- 地点： ~/.continue/config.json （或 %USERPROFILE%\.continue\config.json 在Windows上）
添加到 mcpServers 数组：

{
  "mcpServers": [
    {
      "name": "freshbooks",
      "command": "python3",
      "args": ["/absolute/path/to/freshbooks-mcp-server/src/freshbooks_mcp/server.py"],
      "env": {
        "FRESHBOOKS_API_TOKEN": "your_freshbooks_api_token_here",
        "FRESHBOOKS_BUSINESS_ID": "your_business_id_here"
      }
    }
  ]
}

重新启动Continue.dev

服务器变体

此存储库包括多个服务器实现：

标准服务器 (src/freshbooks_mcp/server.py)-使用MCP SDK和简单的API令牌身份验证
OAuth服务器 (src/freshbooks_mcp/oauth_server.py)-带令牌刷新的完整OAuth流程
简单OAuth服务器 (src/freshbooks_mcp/simple_oauth_server.py)-使用交互式身份验证简化OAuth
原始MCP服务器 (mcp_server.py)-直接实施MCP协议
简单服务器 (simple_server.py)-测试实施最少

选择最适合您身份验证需求的服务器。

快速开始

要手动测试服务器，请执行以下操作：

# Using the standard server
python3 src/freshbooks_mcp/server.py

# Or using the run script
python3 run_server.py

服务器通过MCP协议的stdio（标准输入/输出）进行通信。

可用工具

配置后，您的AI助手将可以使用以下FreshBooks工具：

读取操作

get_clients -从您的FreshBooks帐户获取所有客户
get_invoices -检索所有发票
get_projects -获取所有项目
get_expenses -取回所有费用
get_time_entries -获取所有时间跟踪条目

写入操作（仅限OAuth服务器）

create_client -在FreshBooks中创建新客户端
create_invoice -创建新发票
create_project -创建新项目

OAuth专用工具（OAuth服务器）

authenticate -启动OAuth身份验证流程（打开浏览器进行授权）

故障排除

服务器未出现在Cursor/Claude中

检查Python路径：确保 python3 在你的路径。测试：
```
which python3  # macOS/Linux
where python3  # Windows
```
验证绝对路径：在MCP配置中使用绝对路径。相对路径可能不起作用。
检查环境变量：确保您的FreshBooks凭据在 env MCP配置的一部分。
重新启动客户端：更改配置后，完全重新启动Cursor、Claude Desktop或您的AI客户端。
检查日志：在以下位置查找错误消息：
- 光标：查看→ 输出→ 选择“模型上下文协议”
- Claude Desktop：检查应用程序日志

身份验证问题

API代币：确保您的 FRESHBOOKS_API_TOKEN 有效且具有适当的权限
商业标识：验证您的 FRESHBOOKS_BUSINESS_ID 匹配您的FreshBooks帐户
OAuth：对于OAuth服务器，请确保 FRESHBOOKS_CLIENT_ID 和 FRESHBOOKS_CLIENT_SECRET 是正确的

未找到Python模块

如果收到“ModuleNotFoundError”，请安装依赖项：

cd /path/to/freshbooks-mcp-server
pip install -e .

获取FreshBooks API凭据

API令牌身份验证:
- 登录您的FreshBooks帐户
- 前往设置→ 集成→ API
- 生成API令牌
- 记下您的企业/帐户ID
OAuth身份验证:
- 访问 FreshBooks开发者门户
- 创建新的OAuth应用程序
- 设置重定向URI: https://localhost:8080/callback
- 复制客户端ID和客户端密码

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件