Norman Finance MCP Server

What is Norman Finance MCP Server about?

Enables AI models to interact with the Norman Finance platform, exposing accounting, invoicing, company data, client records, tax information, and document management through a standardized protocol.

How to use Norman Finance MCP Server?

Remote (recommended)

1. Install the MCP client via npm:

   npx mcp-remote https://mcp.norman.finance/sse
   

2. When the client connects, a login page appears; authenticate with your Norman Finance credentials.
3. The server returns OAuth tokens automatically, allowing seamless tool integration.

Local development

1. Clone the repository and install the Python package:

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

2. Provide credentials via environment variables (or a .env file):

   export NORMAN_EMAIL=you@example.com
   export NORMAN_PASSWORD=yourpassword
   export NORMAN_ENVIRONMENT=production
   

3. Run the server:

   python -m norman_mcp --transport sse   # for SSE/OAuth flow
   python -m norman_mcp --transport stdio # for stdin/stdout (Claude Desktop)
   

4. Configure your AI client (Claude Desktop, MCP Inspector, etc.) to point to the server URL (http://localhost:3001 by default).

Key Features

• Secure authentication – OAuth for SSE clients; email/password via environment variables for stdio.
• Company management – Retrieve balances, VAT insights, and company details.
• Accounting – List transactions, categorise them, and query financial insights.
• (e‑)Invoicing – Create, view, send, and manage one‑off or recurring invoices.
• Client CRM – Add, update, and query client records.
• Tax reporting – Generate tax reports, preview official Finanzamt PDFs, and file taxes.
• Document handling – Upload and manage receipts, invoices, and other attachments.
• Ready‑to‑use integrations – Cursor, Claude.ai, Claude Desktop, and generic MCP clients.

Use Cases

• Automated VAT filing – AI drafts and submits VAT reports directly from transaction data.
• Transaction insight generation – Conversational agents provide spending analysis and cash‑flow forecasts.
• Syncing external payments – Connect Stripe or other payment gateways to Norman Finance via AI workflows.
• Invoice overdue management – Detect overdue invoices, send reminders, and update payment status.
• Receipt‑driven bookkeeping – Parse Gmail receipts, create corresponding transactions, and store documents.

FAQ

Q: Do I need to generate an API token? A: No. The remote server uses OAuth, and the local server reads credentials from environment variables.

Q: Which transport should I use? A: SSE (OAuth) for web‑based tools (Claude, MCP Inspector). Use stdio for Claude Desktop or command‑line integrations.

Q: Can I run the server in a sandbox environment? A: Yes. Set NORMAN_ENVIRONMENT=sandbox to target the development environment.

Q: How do I expose the server publicly for OAuth callbacks? A: Set NORMAN_MCP_PUBLIC_URL to a reachable URL (e.g., via ngrok) before starting the server.

Q: What ports does the server listen on by default? A: Host 0.0.0.0 and port 3001 (configurable via NORMAN_MCP_HOST and NORMAN_MCP_PORT).

Norman Finance MCP Server

This Model Context Protocol (MCP) server enables AI to interact with the Norman Finance API, allowing access to accounting, invoices, companies, clients, taxes, and more through a standardized protocol.

[!NOTE]

The Norman Finance MCP Server is currently in Beta. We welcome your feedback and encourage you to report any bugs by opening an issue here.

Features

• 🔐 Authentication: Securely authenticate with the Norman Finance account
• 💼 Company Management: Manage your company details, get company balance, VAT insgihts, etc
• 📊 Accounting: Keep an eye on your transactions, categorization
• 📝 (e-)Invoicing: Make, view, send, and handle invoices. You can even set up recurring ones based on your contracts
• 👥 Client Management: Create and manage your clients (CRM)
• 💰 Taxes: View tax information and reports, generate official Finanzamt PDF previews and file your taxes
• 📄 Documents: Upload and manage attachments (receipts, invoices, docs, etc)

👇 Use case examples with Claude Desktop — toggle

Prerequisites

Before using this MCP server, you need to:

1. Create an account on Norman Finance
2. Have your email and password ready for authentication

Remote MCP Server

Norman now offers a hosted remote MCP server at:

https://mcp.norman.finance/sse

The remote MCP is recommended because it utilizes OAuth authentication, enabling you to log in directly with your Norman account without the need to create or manage access tokens manually.

Installation

Cursor

To add the Norman MCP server to Cursor, copy and paste the following deeplink into your browser:

cursor://anysphere.cursor-deeplink/mcp/install?name=norman-finance-mcp&config=eyJjb21tYW5kIjoibnB4IiwidHlwZSI6InNzZSIsImFyZ3MiOlsibWNwLXJlbW90ZSIsImh0dHBzOi8vbWNwLm5vcm1hbi5maW5hbmNlL3NzZSJdfQ==

---

Claude.ai Integrations

Adding the Norman MCP Server to Claude.ai:

For Claude Max:

1. Head to Settings > Profile
2. Find the "Integrations" section
3. Tap "Add more"
4. Enter the Norman MCP server URL: https://mcp.norman.finance/sse
5. Click "Add" to finish up

For Claude Enterprise & Teams:

1. Go to Settings > Integrations (for Teams) or Settings > Data management (for Enterprise)
2. Find the "Integrations" section
3. Hit "Add more"
4. Enter the Norman MCP server URL: https://mcp.norman.finance/sse
5. Click "Add" to finish up

Enabling the Norman Integration:

1. Start a chat with Claude.
2. Open the Search and tools menu.
3. Click "Connect" to link your Norman account.
5. After connecting, use the same menu to turn on specific Norman tools.

---

Adding to Claude Desktop

To run the Norman Finance MCP server with Claude Desktop, you can use the instruction above or add it manually using the following steps:

1. Download and Configure Claude Desktop

1. Download Claude Desktop.

2. Launch Claude and navigate to: Settings > Developer > Edit Config.

3. Update your claude_desktop_config.json file with the following configuration:

Remote MCP

{
  "mcpServers": {
    "norman-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.norman.finance/sse"]
    }
  }
}

Local MCP

Install uv

Follow the instructions here: Installing uv

{
  "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"
      }
    }
  }
}

Configuration

Authentication Methods

The Norman MCP server supports two authentication methods:

1. OAuth Authentication (for SSE transport)

When using the server with MCP Inspector, Claude, or other SSE clients, the server uses OAuth 2.0 authentication:

1. Start the server with SSE transport:

   python -m norman_mcp --transport sse
   

2. When connecting to the server, you'll be directed to a login page

3. Enter your Norman Finance credentials

4. You'll be redirected back to your application with authentication tokens

2. Environment Variables (for stdio transport)

When using the server with Claude Desktop or stdin/stdout communication, provide credentials through environment variables:

# .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

Environment Variables

The server can be configured using these environment variables:

# Authentication (for stdio transport)
NORMAN_EMAIL=your-email@example.com
NORMAN_PASSWORD=your-password
NORMAN_ENVIRONMENT=production  # or "sandbox" for the development environment

# Server configuration
NORMAN_MCP_HOST=0.0.0.0  # Host to bind to
NORMAN_MCP_PORT=3001     # Port to bind to
NORMAN_MCP_PUBLIC_URL=http://example.com  # Public URL for OAuth callbacks (important for remote access)
NORMAN_API_TIMEOUT=200   # Request timeout in seconds

Development

This section is for contributors who want to develop or extend the Norman Finance MCP server.

Local setup

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

Then update your claude_desktop_config.json file to point to the Python module directly:

{
  "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"
      }
    }
  }
}

Do you have a feature idea or something you'd like to see? Share your suggestion

---