@aurbi/mcp-ro-freescout

read-only MCP server for FreeScout helpdesk.

Connect Claude to your FreeScout helpdesk. Ask Claude questions about your support conversations, customers, and mailboxes — no coding required.

Prerequisites

Node.js must be installed on your computer.

1. Go to https://nodejs.org
2. Click the LTS download button (the left one — it says "Recommended for most users")
3. Run the installer and accept all defaults
4. When it finishes, close and reopen any windows you have open

That's it. You do not need to understand what Node.js is — it just needs to be installed.

Get your FreeScout API key

1. Log in to your FreeScout instance as an administrator
2. Click Manage in the top navigation bar
3. Go to Settings → API & Webhooks
4. Copy the API key shown on that page

Keep this key handy — you'll paste it into the config file below.

Installation (Claude Desktop on Windows)

There is no installer to run. You just edit one config file and restart Claude.

Step 1 — Find the config file

Open File Explorer and paste this into the address bar at the top, then press Enter:

%APPDATA%\Claude

You should see a file called claude_desktop_config.json. If that folder or file does not exist yet, open Claude Desktop at least once first, then try again.

Step 2 — Edit the config file

Right-click claude_desktop_config.json and open it with Notepad (or any text editor).

If the file is empty or contains only {}, replace everything with the block below.

If the file already has content (other MCP servers), add the "freescout" section inside the existing "mcpServers" object — do not replace the whole file.

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["-y", "@aurbi/mcp-ro-freescout"],
      "env": {
        "FREESCOUT_BASE_URL": "https://your-freescout-instance.com",
        "FREESCOUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace:

• https://your-freescout-instance.com with the URL you use to access FreeScout
• your_api_key_here with the API key you copied in the previous section

Step 3 — Save and restart

Save the file, then fully quit and reopen Claude Desktop.

Step 4 — Verify it works

In a new Claude conversation, type:

List my FreeScout mailboxes

Claude should respond with a list of your mailboxes. If it does, everything is working.

What Claude can do with this

Once connected, you can ask Claude things like:

• "Show me all open conversations in the Support mailbox"
• "Summarize the last 10 conversations tagged 'billing'"
• "Find conversations from [email protected]"
• "What's the full thread for conversation #482?"
• "List unassigned conversations updated in the last 7 days"

Available tools

These are the actions Claude can take on your behalf. You don't need to call them directly — Claude picks the right one based on what you ask.

| Tool | What it does | |------|-------------| | list_conversations | Browse conversations with official filters (mailboxId, folderId, status, tag, assignedTo, createdSince, updatedSince, number, pageSize) | | get_conversation | Fetch a single conversation by ID | | search_conversations | Search conversations with advanced query support where your FreeScout version documents it | | get_conversation_with_threads | Fetch a conversation plus its full message thread via dedicated GET, with 405 fallback to embedded threads | | get_threads | Fetch just the messages for a conversation via dedicated GET, with 405 fallback to embedded threads | | list_customers | Browse or search customer records with filters like mailbox, firstName, lastName, modifiedSince, sortField, sortOrder, query, page | | get_customer | Fetch a single customer by ID | | list_mailboxes | List all mailboxes (useful for finding mailbox IDs) | | list_folders | List folders within a mailbox (inbox, mine, closed, etc.) | | list_users | List agents/users, optionally filtered by mailbox | | get_current_user | Identify the agent associated with the configured API key |

Note: This is a read-only connection. Claude can view your FreeScout data but cannot create, edit, or delete anything.

Troubleshooting

Claude says it doesn't know about FreeScout tools

• Double-check that you saved claude_desktop_config.json after editing it
• Make sure you fully quit and reopened Claude Desktop (not just closed the window)
• Check that the JSON in the config file is valid — every { must have a matching }, every line except the last in a block must end with a comma

"API key is invalid or missing" error

• Re-copy your API key from FreeScout (Manage → Settings → API & Webhooks)
• Make sure there are no extra spaces before or after the key in the config file

"Could not connect to FreeScout" or network error

• Check that FREESCOUT_BASE_URL is the exact URL you use to open FreeScout in a browser
• Include https:// at the start; do not include a trailing /
• Confirm your FreeScout instance is reachable from your computer

The config file doesn't exist

Open Claude Desktop, wait for it to load fully, then close it. The config folder should now exist. If it still doesn't, check that Claude Desktop is installed and has been opened at least once.

Thread reads return 405

Some older or mismatched FreeScout API modules return 405 for the documented thread route. These tools fall back from GET /conversations/{id}/threads to GET /conversations/{id}?embed=threads. If both paths fail, compare your instance /api/docs with the installed API & Webhooks module version.

Validating your JSON

If you're unsure whether your config file is valid JSON, paste it into https://jsonlint.com — it will highlight any errors.

For developers

# clone and install
git clone https://github.com/aurbi/mcp-ro-freescout
cd mcp-ro-freescout
npm install

# run in dev mode (uses tsx, reads .env)
cp .env.example .env   # fill in your values
npm run dev

# test and build
npm test
npm run build

Requires Node.js >= 18. Written in TypeScript; compiled output in dist/. See docs/specs/mcp-server-design.md for architecture details.