项目简介

Norman Finance MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在连接大型语言模型 (LLM) 与 Norman Finance API。它允许LLM以标准化的方式访问和操作Norman Finance的各项财务和业务数据，例如公司信息、会计交易、发票、客户、税务和文档等。通过此服务器，LLM能够理解和处理财务上下文，执行诸如创建交易、发送发票、查询税务信息等任务，从而实现智能化的财务管理助手应用。

主要功能点

安全认证：通过 Norman Finance API 进行安全身份验证。
公司管理：查看和更新公司详细信息。
会计处理：访问和管理财务交易记录。
电子发票：创建、查看、发送和管理合规的电子发票，例如基于合同数据创建定期发票。
客户管理：创建和管理客户信息。
税务管理：查看税务信息和报告，生成税务局PDF预览和申报税务。
文档管理：上传和管理附件文档。

安装步骤

使用 Claude Desktop 安装 (通过 PyPI)

安装 uv (推荐): uv 是一个快速的 Python 包安装和虚拟环境管理工具，可以显著加速安装过程。请根据 uv 安装指南完成安装。
下载和配置 Claude Desktop:
- 下载 Claude Desktop 客户端。
- 启动 Claude，进入 "Settings" (设置) -> "Developer" (开发者) -> "Edit Config" (编辑配置)。
- 在打开的 'claude_desktop_config.json' 文件中，添加或修改 'mcpServers' 部分，配置 Norman Finance MCP 服务器。
```
{
  "mcpServers": {
    "norman-mcp-server": {
      "command": "<home_path>/.local/bin/uvx",
      "args": [
        "--from",
        "norman-mcp-server@latest",
        "norman-mcp"
      ],
      "env": {
        "NORMAN_EMAIL": "[email protected]",
        "NORMAN_PASSWORD": "your-password",
        "NORMAN_ENVIRONMENT": "production"
      }
    }
  }
}
```
配置参数说明:
- '"norman-mcp-server"': 服务器名称，可以自定义。
- '"command"': MCP 服务器的启动命令。如果使用 'uv' 安装，通常为 '"<home_path>/.local/bin/uvx"'。 '<home_path>' 需要替换为您的用户Home目录路径。
- '"args"': 传递给启动命令的参数。
  - '"--from", "norman-mcp-server@latest"': 使用 'uvx' 从 PyPI 安装 'norman-mcp-server' 包的最新版本。
  - '"norman-mcp"': 指定要运行的模块或入口点。
- '"env"': 设置环境变量。
  - '"NORMAN_EMAIL"': 您的 Norman Finance 账户邮箱。 请替换为您的真实邮箱。
  - '"NORMAN_PASSWORD"': 您的 Norman Finance 账户密码。 请替换为您的真实密码。
  - '"NORMAN_ENVIRONMENT"': 指定 API 环境，'"production"' 为正式环境，'"sandbox"' 为沙箱 (开发) 环境。

从源代码安装

如果您希望从源代码运行 MCP 服务器：

克隆仓库:

git clone https://github.com/norman-finance/norman-mcp-server.git
cd norman-mcp-server

安装:
```
pip install -e .
```

配置 Claude Desktop:

按照上述步骤打开 'claude_desktop_config.json' 文件。
修改配置文件内容如下，指向本地 Python 模块：

{
  "mcpServers": {
    "norman-mcp-server": {
      "command": "<path_to_your_python>/python",
      "args": ["-m", "norman_mcp"],
      "env": {
        "NORMAN_EMAIL": "[email protected]",
        "NORMAN_PASSWORD": "your-password",
        "NORMAN_ENVIRONMENT": "production"
      }
    }
  }
}

配置参数说明:

'"command"': Python 解释器路径。 '<path_to_your_python>/python' 需要替换为您 Python 解释器的实际路径 (例如 '/usr/bin/python3' 或 'C:\Python39\python.exe')。
'"args"': '["-m", "norman_mcp"]' 表示以模块方式运行 'norman_mcp'。
'"env"': 环境变量配置与 PyPI 安装方式相同，请务必替换为您自己的 Norman Finance 账户信息。

服务器配置

您可以通过以下两种方式配置 Norman Finance 账户凭据和 API 环境：

环境变量

编辑 '.env' 文件，添加您的 Norman Finance 账户信息：

# .env
[email protected]        # 替换为您的邮箱
NORMAN_PASSWORD=your-password             # 替换为您的密码
NORMAN_ENVIRONMENT=production           # 可选 "production" 或 "sandbox"
NORMAN_API_TIMEOUT=200                  # 可选，API 请求超时时间 (秒)

命令行参数

您也可以在启动服务器时通过命令行参数传递凭据：

norman-mcp --email [email protected] --password your-password --environment production

基本使用方法

启动 MCP 服务器:
- 如果使用 PyPI 安装，直接运行命令：
```
norman-mcp
```
- 如果从源代码安装，运行命令：
```
python -m norman_mcp
```
连接 MCP 客户端:
- 配置您的 MCP 客户端 (例如 Claude Desktop) 连接到 'norman-mcp-server' 服务器。Claude Desktop 的配置方法已在 安装步骤 中说明。
- 客户端通过标准输入/输出 (stdio) 协议与服务器通信。
与 LLM 交互:
- 在 MCP 客户端中，您可以指示 LLM 使用 Norman Finance MCP 服务器提供的 资源 (Resources) 和 工具 (Tools) 来访问财务数据或执行操作。
- 资源 (Resources) 允许 LLM 获取数据，例如：
- 'company://current': 获取当前公司详情。
- 'transactions://list/1/10': 获取第一页的 10 条交易记录。
- ... (更多资源请参考仓库 README)
- 工具 (Tools) 允许 LLM 执行操作，例如：
- 'create_transaction(amount=-129.99, description="Office supplies", cashflow_type="EXPENSE")': 创建一笔支出交易。
- 'create_invoice(client_id, items, ...)': 创建发票。
- ... (更多工具请参考仓库 README)
- 提示模板 (Prompts) 提供预定义的交互模式，例如 'create_transaction_prompt(amount, description, cashflow_type)' 用于引导 LLM 创建交易。

请参考仓库的 README.md 文件获取更详细的资源、工具和提示模板列表，以及更多使用示例。

关键词