Freshbooks MCP Server (Bitovi)

FreshBooks MCP服务器

一 MCP（模型上下文协议） 服务器 FreshBooks API.将Claude连接到您的FreshBooks帐户，以阅读发票、客户、费用、项目、服务等，并管理付款和时间条目。

支持两种模式：

• 标准 --适用于Claude Desktop和MCP Inspector（无需服务器）
• HTTP+SSE --用于claude.ai自定义连接器（需要公共HTTPS URL）

工具

先决条件

• Node.js v20.6或更高版本
• FreshBooks帐户
• FreshBooks应用程序（免费）-在 my.freshbooks.com/#/developer

设置

git clone https://github.com/bitovi/freshbooks-mcp-server
cd freshbooks-mcp-server
npm install
npm run build
cp .env.example .env

编辑 .env 并设置您的FreshBooks应用程序凭据：

FRESHBOOKS_CLIENT_ID=your_client_id
FRESHBOOKS_CLIENT_SECRET=your_client_secret

克劳德桌面（stdio）

这是使用服务器的最简单方法。Claude Desktop直接通过stdio与它通信，不需要HTTP服务器或公共URL。

1.获取FreshBooks刷新令牌

启动HTTP服务器以完成OAuth流程一次：

npm run dev:http

在单独的终端中，打印auth URL：

npm run auth-url

在浏览器中打开打印的URL，并使用FreshBooks登录。你的 refresh_token 和 session_token 在浏览器中显示。FreshBooks代币也保存到 ~/.freshbooks-mcp/sessions.json.

复制 refresh_token 值并将其添加到 .env:

FRESHBOOKS_REFRESH_TOKEN=your_refresh_token

服务器在启动时将其交换为访问令牌，并自动处理续订——除非您在FreshBooks中撤销应用程序的访问权限，否则您只需要执行一次。

2.添加到克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "freshbooks": {
      "command": "/path/to/node",
      "args": ["/path/to/freshbooks-mcp-server/dist/index.js"],
      "env": {
        "MODE": "stdio"
      }
    }
  }
}

替换 /path/to/node 包含Node.js二进制文件的完整路径(which node)以及 /path/to/freshbooks-mcp-server 以及通往此仓库的绝对路径。

nvm用户： Claude Desktop不会继承您的shell环境。使用节点二进制文件的完整路径，例如。 /Users/you/.nvm/versions/node/v22.8.0/bin/node.

重新启动克劳德桌面。FreshBooks工具将出现在聊天输入的锤子菜单中。

claude.ai自定义连接器（HTTP+SSE）

Claude.ai自定义连接器需要一个公共HTTPS URL。您可以使用以下命令测试连接器 吸烟 或通过 部署到AWS.

本地测试

1.启动服务器

npm run dev:http

2.信任自签名证书

打开 https://localhost:3443 在您的浏览器中。点击 高级→ 转到本地主机 接受自签名证书。您只需在每个浏览器会话中执行一次此操作，否则OAuth重定向将被阻止。

3.将回调URI添加到您的FreshBooks应用程序

在您的FreshBooks开发者控制台中，添加：

https://localhost:3443/oauth/callback

4.获取身份验证URL

npm run auth-url

在浏览器中打开打印的URL，使用FreshBooks登录，您将在页面上看到您的会话令牌。

5.测试SSE端点

curl -sk https://localhost:3443/sse -H "Authorization: Bearer "

设置ngrok

如果你想在claude.ai中使用真实证书进行本地测试，请使用ngrok：

# Add to .env:
HTTPS=false
SERVER_URL=https://your-subdomain.ngrok-free.app

npm run dev:http   # Terminal 1
ngrok http 3000    # Terminal 2

添加 https://your-subdomain.ngrok-free.app/oauth/callback 转到您的FreshBooks应用程序，然后运行 npm run auth-url.

添加到claude.ai

首选 设置→ 集成→ 添加集成 并输入您的SSE URL：

https://your-subdomain.ngrok-free.app/sse   # ngrok
https://freshbooks-mcp.yourdomain.com/sse   # production

Claude会提示您登录FreshBooks。经过身份验证后，这些工具将在您的对话中可用。

部署到AWS（EC2+nginx）

建议的设置是运行nginx作为反向代理的EC2实例，并使用Let's Encrypt获得免费的TLS证书。会话存储在磁盘上，以便在重新启动后继续运行。

建筑

claude.ai → ALB (or Elastic IP) → nginx (HTTPS/443) → Node.js (HTTP/3000)

如果你不需要自动扩展，你可以跳过ALB，直接在EC2上使用nginx+Let’s Encrypt。

1.启动EC2实例

• AMI： 亚马逊Linux 2023（或Ubuntu 22.04）
• 实例类型： t3.micro（免费套餐）或t3.small
• 安全组入站规则：

- SSH（22）--仅限您的IP - HTTP（80）-任何地方（Let's Encrypt验证所需） - HTTPS（443）-任何地方

• 附上 弹性IP 因此，您的DNS记录在重新启动后保持稳定

2.将域指向实例

在Route 53（或任何DNS提供商）中，创建 一个记录 将您的域指向Elastic IP：

freshbooks-mcp.yourdomain.com  →  

3.安装Node.js 22和nginx

# Amazon Linux 2023
sudo dnf install -y nginx git
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

# Ubuntu 22.04
sudo apt update && sudo apt install -y nginx git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs

全局安装PM2：

sudo npm install -g pm2

4.部署应用程序

git clone https://github.com/bitovi/freshbooks-mcp-server /srv/freshbooks-mcp
cd /srv/freshbooks-mcp
npm install
npm run build
mkdir -p logs

cp .env.example .env
nano .env   # fill in credentials (see Environment variables below)

最小 .env 用于生产：

FRESHBOOKS_CLIENT_ID=your_client_id
FRESHBOOKS_CLIENT_SECRET=your_client_secret
MODE=http
HTTPS=false
SERVER_URL=https://freshbooks-mcp.yourdomain.com

PORT 默认为 3000 当 HTTPS=false，因此无需显式设置。

5.配置nginx

创建 /etc/nginx/conf.d/freshbooks-mcp.conf:

server {
    listen 80;
    server_name freshbooks-mcp.yourdomain.com;
    # Let's Encrypt challenge + redirect everything else to HTTPS
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl;
    server_name freshbooks-mcp.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/freshbooks-mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/freshbooks-mcp.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for SSE — disable buffering so events stream immediately
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        # Keep SSE connections open for up to 24 hours
        proxy_read_timeout 86400s;
        chunked_transfer_encoding on;
    }
}

测试和重新加载：

sudo nginx -t && sudo systemctl reload nginx

6.获取TLS证书

sudo dnf install -y python3-certbot-nginx   # Amazon Linux 2023
# or: sudo apt install -y certbot python3-certbot-nginx   # Ubuntu

sudo certbot --nginx -d freshbooks-mcp.yourdomain.com

Certbot自动配置nginx，并通过systemd定时器设置自动续订。

7.使用PM2启动服务器

cd /srv/freshbooks-mcp
pm2 start ecosystem.config.cjs
pm2 save              # persist across reboots
pm2 startup           # follow the printed command to enable on boot

有用的命令：

pm2 logs freshbooks-mcp     # tail logs
pm2 reload freshbooks-mcp   # zero-downtime restart after code changes
pm2 status                  # check process health

8.更新FreshBooks和claude.ai

在FreshBooks开发者控制台中，添加生产重定向URI：

https://freshbooks-mcp.yourdomain.com/oauth/callback

在claude.ai→ 设置→ 集成→ 添加集成，输入：

https://freshbooks-mcp.yourdomain.com/sse

Claude将引导您了解FreshBooks OAuth流程。在那之后，所有的工具都是活的。

正在更新服务器

cd /srv/freshbooks-mcp
git pull
npm install
npm run build
pm2 reload freshbooks-mcp

备注

• 会话 存储在 ~/.freshbooks-mcp/sessions.json 在EC2实例上。由于EC2具有持久性文件系统，会话在重启和部署后仍然有效。
• ALB： 如果稍后添加应用程序负载平衡器，请设置其 空闲超时为3600秒 （默认60将丢弃长期SSE连接）。nginx的 proxy_read_timeout 在直达时处理这个问题。
• 日志 首选 ./logs/ 在项目目录中，由PM2管理。

环境变量

项目结构

src/
  index.ts              Entry point — picks stdio or HTTP based on MODE
  load-env.ts           Minimal .env loader (no dotenv dependency)
  config.ts             Config from environment variables
  mcp-server.ts         Creates the McpServer and registers all tools
  http-server.ts        Express server with SSE transport and OAuth2 proxy
  stdio-server.ts       Stdio transport with token resolution
  freshbooks/
    client.ts           FreshBooks API client
    types.ts            TypeScript types for API responses
  tools/
    users.ts            get_current_user, list_team_members, get_team_member
    clients.ts          Client tools
    invoices.ts         Invoice tools
    expenses.ts         Expense tools
    payments.ts         Payment tools
    projects.ts         Project tools
    time-entries.ts     Time entry tools
    items.ts            Item tools
    services.ts         Service tools
  scripts/
    auth-url.ts         Prints the FreshBooks OAuth URL for local testing