datev-mcp

Ask your AI assistant about your DATEV bookkeeping, payroll and documents in plain words, and let it act on them only after you have seen exactly what it will do.

What this is, in plain words

DATEV holds the books of most German small and medium businesses. Getting a number out of it, uploading a receipt, or checking a payroll export usually means logging in, clicking through several screens and copying values by hand.

datev-mcp connects an AI assistant (Claude, Cursor, VS Code Copilot or any client that speaks the Model Context Protocol) to the official DATEV APIs. You ask "what is the balance on account 1200 for client 455148-1 this year?" and the assistant fetches it from DATEV for you. When an action would change data, such as uploading a document or importing bookings, the assistant first shows you a preview and does nothing until you agree.

It is built for tax advisors, bookkeepers, and the developers who build tools for them.

Related MCP server: Red MCP Server

What you get

• Answers without clicking. Clients, fiscal years, sums and balances, account postings and the chart of accounts come straight from DATEV into the conversation.

• Nothing changes behind your back. Every write that changes bookings, files or records returns a preview first. The real call only runs with a one-time confirmation code that matches that exact preview, so the assistant cannot quietly swap the file or the target client. The one exception is datev_account_postings, which starts DATEV's read-only postings export job directly.

• Every DATEV operation, not a hand-picked few. All 209 operations across 23 DATEV API specifications are indexed and can be searched and described (health checks only on request), with thirteen focused tools for the everyday cases. Every operation that takes a file upload can be sent with datev_upload_file, after a preview.

• Your files stay yours. The server refuses to send anything from hidden folders (where SSH keys and cloud logins live) or anything that looks like a key or credentials file.

• Honest answers. If DATEV returns an error, an incomplete page or an answer shape the accounting tools do not understand, you get told instead of a fake empty list. Rows the tools cannot read are counted in the answer (skipped_rows, rows_without_account), and a chart of accounts with no readable row is refused.

From zero to your first answer

You need a DATEV developer account with an app registered for the sandbox, and Node.js 22 or newer. The DATEV portal steps are in docs/SETUP.md. Plan about 15 minutes the first time.

Every screenshot below was taken on 2026-11-07 against the DATEV sandbox, which holds test data only. The DATEV logo is blurred on purpose; this project is not affiliated with DATEV.

1. Install and build

git clone https://github.com/mjmirza/datev-mcp.git
cd datev-mcp
npm install
npm run specs      # downloads DATEV's public API specs into specs/ (never committed)
npm run build

2. Add your DATEV app credentials

Copy the example settings file and fill in the client id and secret from your app in the DATEV developer portal.

cp .env/.env.example .env/.env.local
# edit .env/.env.local: DATEV_CLIENT_ID and DATEV_CLIENT_SECRET

Git ignores .env/.env.local. Every setting is explained in .env/README.md. A password manager that injects the two values at start is safer than a file, and either works. Never paste the secret into a chat.

3. Sign in once

node --env-file=.env/.env.local dist/index.js login

A browser window opens at DATEV's sandbox login. These are the four screens you will see.

3a. Choose how to sign in. For a sandbox test account, pick DATEV-Benutzerkonto and press Next.

3b. Enter your sandbox username and password. You type these into DATEV's own page. datev-mcp never sees them.

3c. Grant the permissions. DATEV lists what the app may do and where it will send you back (a one-time localhost address on your own machine). Press "I agree" at the bottom.

3d. Done. The browser shows a short confirmation and your terminal prints Logged in to DATEV sandbox. The session is saved on your machine with owner-only permissions.

Working over SSH, or want a different browser? Set DATEV_MCP_NO_BROWSER=1 and the command only prints the link.

4. Check that everything works

node --env-file=.env/.env.local dist/index.js doctor

Six green lines mean the credentials, the operation index, the saved session, the token and two live DATEV calls all work.

5. Connect your AI client

Example for Claude Code. Other MCP clients take the same command and arguments.

claude mcp add datev -- node --env-file=/absolute/path/to/datev-mcp/.env/.env.local /absolute/path/to/datev-mcp/dist/index.js

6. Ask your first question

Type "which clients can I reach in DATEV?". That is your first win.

What the answers look like

These are real answers from the DATEV sandbox, unedited apart from shortening long lists. The questions are what you type, the tool line is what your assistant calls behind the scenes.

Your clients and the data services each one has switched on.

Search the client's real chart of accounts in plain words.

Sums and balances (Summen- und Saldenliste) for a fiscal year.

Every posted booking of the year. DATEV prepares this export as a background job. The server waits for it, reads all pages and tells you whether the list is complete.

Booking something. Preview first, nothing sent. The assistant builds and checks a DATEV booking file, then shows you what it would import and where. It can only send it after you agree, using the confirmation code tied to this exact file.

The tools

How well it is tested

Every number below comes from a real run on 2026-11-07. The method and how to reproduce each one is in docs/VALIDATION.md.

Per operation results are in docs/ENDPOINT-AUDIT.md.

Safety in one paragraph

Operation calls only go to the DATEV hosts named in DATEV's specs and never follow a redirect, so your credentials cannot be forwarded elsewhere by them. The login token request and doctor use fetch's default redirect handling. Logins use OAuth with PKCE and the session is stored on your machine with owner-only permissions. Writes need a preview-bound confirmation code. Calls have a time budget, can be cancelled by your AI client, and stop reading an answer once it grows too large. The full threat model is in docs/SECURITY.md.

For developers

src/
  api/client.ts      builds, sends and reads every DATEV request
  auth/              OAuth login, token refresh, session file and its lock
  tools/             the thirteen MCP tools
  setup/             login and doctor commands
scripts/             spec download, operation index, endpoint audit
test/unit/           unit and integration tests
test/evals/run.ts    the offline scenario generator
test/live-sweep.ts   the rate-limited live sandbox crawl
docs/                setup, security, validation, compliance and more

Community

• Got a question? Search the 2,000+ answered questions first. They cover setup, login, safety, every tool, every DATEV operation with its measured sandbox result, and the questions people ask about the DATEV API in DATEV's community, on Reddit and in YouTube walkthroughs.

• Still stuck? Ask in Discussions, Q&A.

• An idea for a tool or a DATEV product? Post it in Discussions, Ideas.

• What is planned? See the project board.

• A security problem? Report it privately through the Security tab.

Before you use real client data

The sandbox may only hold test data. Using this with real clients needs DATEV's paid technical review (Technische Prüfung) for production access. Read docs/COMPLIANCE.md before that step.

More documentation

• Setup

• Security

• Validation

• Endpoint audit

• Compliance

• Accessibility

• Questions and answers, short FAQ

• Over 2,000 answered questions

• Credits

• Changelog

License

Source-available, not open source. An individual may run and study it for personal, non-commercial evaluation with the credit kept intact. Any business or client use, and any derivative work, including one generated by an AI, needs written consent. The full terms are in LICENSE. For a commercial license or help setting it up, reach out through next8n.com.

DATEV is a registered trademark of DATEV eG. This project is independent and is not affiliated with, endorsed by, or sponsored by DATEV eG. See docs/TRADEMARKS.md.