AFAS MCP Server

An open-source Model Context Protocol server for AFAS Profit. It lets AI assistants such as Claude Desktop, Claude Code or Cursor read data through your GetConnectors, look at connector schemas and, only when you switch it on, write through UpdateConnectors.

It is read-only by default. One server process uses one AFAS app connector token, so the assistant can reach only the connectors that token allows.

What it does

• Reads by default. Insert, update and delete tools exist only when AFAS_ALLOW_WRITES=true.
• Uses your connectors. The server sees exactly the GetConnectors and UpdateConnectors that the AFAS app connector behind the token allows. Nothing is bundled or hard-coded.
• Knows the schema. Field definitions come from AFAS metainfo, and write payloads are checked against the UpdateConnector schema before anything is sent.
• Takes readable filters. Filters use a field id and an operator name (contains, greater_than, ...) and are turned into the AFAS query syntax, including OR groups and the JSON filter fallback.
• Runs where your MCP client runs. stdio for desktop clients, streamable HTTP for shared deployments.

How it fits together

flowchart LR
    client["<b>MCP client</b><br/>Claude Desktop · Claude Code · Cursor · ..."]

    subgraph server["afas-mcp-server &nbsp;·&nbsp; one AFAS token &nbsp;·&nbsp; read-only by default"]
        direction TB
        read["<b>Read tools</b> (always on)<br/>afas_connection_info · afas_list_connectors<br/>afas_describe_get_connector · afas_describe_update_connector<br/>afas_get_rows · afas_validate_payload"]
        filters["Filters by field id and operator name,<br/>rendered to the AFAS query syntax"]
        write["<b>Write tools</b> (only with AFAS_ALLOW_WRITES=true)<br/>afas_insert · afas_update · afas_delete"]
        validate["Offline validation against<br/>the UpdateConnector schema"]
        read --> filters
        write --> validate
    end

    subgraph afas["AFAS Profit REST services"]
        direction TB
        meta["metainfo"]
        get["GetConnectors"]
        upd["UpdateConnectors"]
    end

    client <-- "MCP over stdio<br/>or streamable HTTP" --> server
    read -- "GET" --> meta
    filters -- "GET · skip, take, orderby" --> get
    validate -- "POST · PUT · DELETE" --> upd

    classDef writes fill:#fff4e5,stroke:#e08a00,color:#5c3d00
    class write,validate writes

The assistant discovers connectors and fields through AFAS metainfo, reads rows through GetConnectors with filters and paging, and can only reach UpdateConnectors when the operator has enabled writes, and then only after the payload has been checked against the connector's schema.

Install

1. In AFAS Profit, create an app connector (Algemeen > Beheer > App connector), add the GetConnectors and UpdateConnectors the assistant may use, and create a token for a user. Note the environment number from your AFAS Online URL, e.g. 12345 in https://12345.afasonline.com.

2. Install uv and check the connection:

   export AFAS_MEMBER_ID=12345
   export AFAS_TOKEN='<token><version>1</version><data>YOUR_TOKEN_DATA</data></token>'
   uvx afas-mcp-server --check
   

   You should see the base URL the server will talk to and the Profit version AFAS reports.

3. Register the server with your MCP client. For Claude Desktop, add this to claude_desktop_config.json:

   {
     "mcpServers": {
       "afas": {
         "command": "uvx",
         "args": ["afas-mcp-server"],
         "env": {
           "AFAS_MEMBER_ID": "12345",
           "AFAS_TOKEN": "<token><version>1</version><data>YOUR_TOKEN_DATA</data></token>"
         }
       }
     }
   }
   

   For Claude Code:

   claude mcp add afas -e AFAS_MEMBER_ID=12345 -e AFAS_TOKEN='<token>...</token>' -- uvx afas-mcp-server
   

Until the package is published on PyPI, run it from a checkout instead: uv run afas-mcp-server, or from git with uvx --from git+https://github.com/schubergphilis/afas_mcp_server afas-mcp-server.

Use

Ask your assistant something like "Which AFAS connectors can you use?" or "Show the ten most recently changed employees." It will discover connectors, read their field definitions and page through rows.

Command line: afas-mcp-server [--transport stdio|streamable-http] [--host H] [--port P] [--path /mcp] [--check].

This is the beginning of the README. Read the rest at the original. Read the full README ↗