Norman Finance MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，允许大型语言模型 (LLMs) 与基本的 Norman Finance API 实现进行交互。此服务器通过标准化协议提供对会计、发票、公司、客户、税务等的访问。

功能

• 🔐 身份验证：安全地与 Norman Finance API 进行身份验证
• 💼 公司管理：查看和更新公司详情
• 📊 会计：访问和管理交易
• 📝 (电子)发票：创建、查看、发送和管理合规发票。例如，根据合同数据创建定期发票
• 👥 客户管理：创建和管理客户
• 💰 税务：查看税务信息和报告，生成官方 Finanzamt PDF 预览并报税
• 📄 文档：上传和管理附件

使用 Claude Desktop 的用例示例

以下是一些如何使用 Norman Finance MCP 与 Claude Desktop 的示例：

1. 使用 Gmail 收据创建交易

2. 管理逾期发票

前提条件

在使用此 MCP 服务器之前，您需要：

1. 在 Norman Finance（或对于沙盒环境dev.norman.finance）上创建一个帐户
2. 准备好您的电子邮件和密码以进行身份验证

安装

使用 Claude Desktop 与 Norman MCP 服务器（通过 PyPI）

要运行带有 Claude Desktop 的 Norman Finance MCP 服务器，请按照以下步骤操作：

1. 安装 uv

请参阅此处的说明：安装 uv

2. 下载并配置 Claude Desktop

1. 下载 Claude Desktop。

2. 启动 Claude 并导航至：设置 > 开发者 > 编辑配置。

3. 使用以下配置更新您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "norman-mcp-server": {
      "command": "<home_path>/.local/bin/uvx",
      "args": [
        "--from",
        "norman-mcp-server@latest",
        "norman-mcp"
      ],
      "env": {
        "NORMAN_EMAIL": "your-email@example.com",
        "NORMAN_PASSWORD": "your-password",
        "NORMAN_ENVIRONMENT": "production"
      }
    }
  }
}

从源代码安装

如果您更喜欢从源代码运行 MCP 服务器：

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

然后更新您的 claude_desktop_config.json 文件以直接指向 Python 模块：

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

配置

环境变量

服务器需要使用您的 Norman Finance 凭证进行身份验证。您可以使用环境变量提供这些凭证：

创建一个 .env 文件，并添加如下内容：

# .env
NORMAN_EMAIL=your-email@example.com
NORMAN_PASSWORD=your-password
NORMAN_ENVIRONMENT=production  # or "sandbox" for the development environment
NORMAN_API_TIMEOUT=200  # Request timeout in seconds

命令行参数

或者，您也可以通过命令行参数提供凭证：

norman-mcp --email your-email@example.com --password your-password --environment production

使用

与 Claude 或其他兼容 MCP 的 LLMs 一起使用

1. 启动 MCP 服务器：

norman-mcp

1. 使用 stdio 协议将服务器添加到您的 Claude 配置中。

与 Claude 桌面版集成

您可以使用 MCP CLI 安装服务器：

mcp install norman-mcp

在提示时配置您的 Norman Finance 凭据。

直接执行

您也可以直接运行服务器：

python -m norman_mcp

资源

此 MCP 服务器公开了以下资源：

• company://current - 关于您当前公司的详细信息
• transactions://list/{page}/{page_size} - 带分页的交易列表
• invoices://list/{page}/{page_size} - 带分页的发票列表
• clients://list/{page}/{page_size} - 带分页的客户列表
• taxes://list/{page}/{page_size} - 带分页的税务报告列表
• categories://list - 交易类别列表

工具

MCP 服务器为 Norman Finance API 交互提供了以下工具：

公司管理

• get_company_details() - 获取关于您公司的详细信息
• update_company_details(name, profession, address, etc.) - 更新公司信息
• get_company_balance() - 获取公司的当前余额
• get_company_tax_statistics() - 获取公司的税务统计信息
• get_vat_next_report() - 获取下一个报告期的增值税金额

交易管理

• search_transactions(description, from_date, to_date, min_amount, max_amount, etc.) - 根据条件搜索交易
• create_transaction(amount, description, cashflow_type, etc.) - 创建新的交易
• update_transaction(transaction_id, amount, description, etc.) - 更新现有交易
• categorize_transaction(transaction_amount, transaction_description, transaction_type) - 使用 AI 识别交易类别

发票管理

• create_invoice(client_id, items, etc.) - 创建新发票
• create_recurring_invoice(client_id, items, etc.) - 创建新的定期发票
• get_invoice(invoice_id) - 获取特定发票的详细信息
• send_invoice(invoice_id, subject, body, etc.) - 通过电子邮件发送发票
• link_transaction(invoice_id, transaction_id) - 将交易链接到发票
• get_einvoice_xml(invoice_id) - 获取特定发票的电子发票 XML
• list_invoices(status, from_date, to_date, etc.) - 列出发票（可选过滤）

客户管理

• list_clients() - 获取所有客户的列表
• get_client(client_id) - 获取特定客户的详细信息
• create_client(name, client_type, address, etc.) - 创建新客户
• update_client(client_id, name, client_type, etc.) - 更新现有客户
• delete_client(client_id) - 删除客户

文档管理

• upload_bulk_attachments(file_paths, cashflow_type) - 批量上传多个文件附件
• list_attachments(file_name, linked, attachment_type, etc.) - 获取附件列表，可选过滤条件
• create_attachment(file_path, transactions, attachment_type, etc.) - 创建一个新的附件
• link_attachment_transaction(attachment_id, transaction_id) - 将交易链接到附件

税务管理

• list_tax_reports() - 列出所有可用的税务报告
• get_tax_report(report_id) - 检索特定的税务报告
• validate_tax_number(tax_number, region_code) - 验证特定地区的税号
• generate_finanzamt_preview(report_id) - 为税务报告生成测试版Finanzamt预览
• submit_tax_report(report_id) - 向Finanzamt提交税务报告
• list_tax_states() - 获取可用的税务状态列表
• list_tax_settings() - 获取当前公司的税务设置列表
• update_tax_setting(setting_id, tax_type, vat_type, etc.) - 更新税务设置

提示

MCP服务器提供这些引导提示来帮助用户与Norman Finance交互：

• create_transaction_prompt(amount, description, cashflow_type) - 创建添加新交易的提示
• create_client_prompt(name, client_type) - 创建添加新客户的提示
• send_invoice_prompt(invoice_id) - 创建通过电子邮件发送发票的提示
• search_transactions_prompt(date_range) - 创建搜索交易的提示

示例交互

以下是一些与Norman Finance MCP服务器进行交互的示例：

查看公司详情

You can view your company details by accessing the company resource.
[LLM accesses company://current]

列出交易

To see your recent financial transactions:
[LLM accesses transactions://list/1/10]

创建一个交易

To create a new expense transaction:
[LLM calls create_transaction with amount=-129.99, description="Office supplies", cashflow_type="EXPENSE"]

创建一个发票

To create a new invoice, I'll use the create_invoice tool.
[LLM calls create_invoice with client_id, items, etc.]

开发

本节面向希望开发或扩展Norman Finance MCP服务器的贡献者。

本地开发环境设置

1. 克隆仓库：

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

2. 创建并激活虚拟环境：

   # 使用venv
   python -m venv venv
   source venv/bin/activate  # 在Windows上: venv\Scripts\activate
   
   # 或者使用uv（推荐）
   uv venv
   source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate
   

3. 安装开发依赖项：

   # 使用pip
   pip install -e ".[dev]"
   
   # 或者使用uv
   uv pip install -e ".[dev]"
   

4. 创建包含您的Norman Finance凭据的.env文件：

   cp .env.template .env
   # 编辑.env文件以添加您的凭据
   

以开发模式运行

要使用MCP Inspector在开发模式下运行MCP服务器：

mcp dev norman_mcp/server.py

这将启动服务器并在浏览器中打开MCP Inspector，允许您交互式地测试资源和工具。