freee-mcp

关键词

模型上下文协议OAuth2 PKCEClaude 集成OpenAPI 客户端企业 API 集成

使用说明

  • 项目简介

    • freee-mcp 是一个基于 MCP（Model Context Protocol）的服务器端实现，设计目标是以标准化的 JSON-RPC 协议向 LLM 客户端提供上下文信息和能力。核心职责包括托管资源、注册并执行工具，以及定义/渲染 Prompt 模板，以实现对外部 API 的安全可控访问。它与 Claude 生态（Claude Desktop/Code 插件）紧密结合，允许从 Freee 的 API 进行实际调用并返回结果给 LLM 客户端。

  • 主要功能点

    • MCP 服务器核心：提供标准化的 MCP 服务端框架，通过 JSON-RPC 与客户端通信，支持会话管理、能力声明和多传输通道（当前实现基于 STDIO，未来可扩展为 SSE/WebSocket 等）。
    • 资源管理与数据访问：后端通过 OpenAPI/目标 API（Freee API）进行数据拉取与查询，并对结果进行结构化渲染返回给客户端。
    • 工具注册与执行：注册多种工具（如 OAuth 授权、获取当前用户、切换事业所、列出事业所等），并允许 LLM 通过工具接口完成对外部系统的操作。
    • Prompt 模板与上下文注入：结合 Skill/参考文档实现对 API 用法的上下文注入和渲染，提升对话质量与一致性。
    • 安全认证与会话管理：内置 OAuth2.0 PKCE 流程、令牌管理、授权回调服务以及会话超时控制，支持动态事业所切换。
    • Claude 插件与 Skill 集成：提供针对 Claude 的技能与工具接入能力，便于在 Claude Code/Claude Desktop 中使用。
    • 开发与测试友好：提供完整的单元测试、集成测试、CI 支持和本地开发脚本。

  • 安装步骤

    • 安装依赖与构建
      • 下载安装依赖（推荐使用 pnpm 或 npm）：安装项目依赖、进入开发模式、运行构建与类型检查。
    • 运行与调试
      • 启动开发环境：进入项目后，使用开发命令启动 MCP 服务器（如 pnpm dev）。
      • 构建产物：使用构建命令打包为可执行入口（CLI），以便本地调试或在容器中运行。
    • Claude 集成
      • 在 Claude Desktop 的配置中添加 MCP 服务器条目，指向命令与参数，确保 Claude 能通过标准输入/输出等传输方式与 MCP 服务器通信。
    • 授权与接入
      • 通过 freee-mcp 提供的交互向导完成 OAuth2 授权流程、事业所切换与授权状态查询等操作。

  • 服务器配置（MCP 客户端需要的最小配置示例）

    • 服务器启动配置（JSON 结构，注释文字说明如下）
    • 配置字段要点
      • mcpServers：键为服务器名称，值为启动该 MCP 服务器所需的命令及参数。名称在本实现中通常为 freee，对应服务器的 internal name，便于 Claude 客户端对应绑定。
      • command：启动服务器所使用的命令（如 npx、node、tsx 等）。
      • args：命令的参数数组，通常包含要执行的脚本或入口（如 ['freee-mcp']）。
    • 精确示例（文字描述，不使用代码块）
      • 配置文件示例：
        • mcpServers
          • freee:
            • command: "npx"
            • args: ["freee-mcp"]
      • 说明：
        • server 名称（freee）用于在 Claude 侧引用和区分不同 MCP 服务。
        • command 与 args 指定了如何启动 MCP 服务器进程，例如通过 Node/PNPM 环境执行 freee-mcp 的入口。
    • 说明：以上配置信息是给 MCP 客户端使用的配置，MCP 客户端需要读取该配置并启动对应 MCP 服务器进程，与服务器端建立连接并通过 MCP 协议进行通信。服务器端代码中已经实现了通过 STDIO 传输进行对接的能力。

  • 基本使用方法

    • 启动与交互
      • 启动 MCP 服务器（本实现的默认传输为 STDIO，适合本地开发和 Claude 集成测试场景）。
      • 通过 Claude 插件/Skill 调用注册的工具与 API，获取数据、执行操作并渲染结果。
    • 身份与会话
      • 使用 OAuth 2.0 PKCE 模式完成授权，获取访问令牌并对 Freee API 进行请求。
      • 支持多事业所环境，当前所选事业所将对后续 API 请求产生影响。
    • 常见操作
      • 查询当前用户、切换事业所、列出事业所、调用 Freee API 的 GET/POST/PUT/DELETE 等工具。
      • 使用 openapi/OpenAPI 参考工具，获取端点信息、执行端点测试。

  • 关联与扩展

    • 本实现提供了对 Client Mode Tool 的生成，支持 freee_api_get/freee_api_post/freee_api_put/freee_api_delete/freee_api_patch 与 freee_api_list_paths 等工具，便于通过 MCP 与外部 API 的交互。
    • 具备 Tokens、OAuth、Token 迁移、配置管理等模块，支持多环境部署和持久化凭证。

  • 结果与部署注意点

    • MCP 服务端实现要确保依赖环境（Node/NPM、云端/本地 OpenAPI 方案、OAuth 回调端口等）按照项目要求配置好。
    • Claude 插件/Skill 的版本兼容性需要与 MCP 服务端实现保持一致，以确保技能注入和工具调用的正确性。

服务器信息

访问项目