{"_id":"@aurbi/mcp-ro-freescout","name":"@aurbi/mcp-ro-freescout","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aurbi/mcp-ro-freescout","version":"1.0.0","description":"read-only MCP server for FreeScout helpdesk — insight generation via Claude","type":"module","bin":{"mcp-ro-freescout":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","test":"node --import tsx --test test/*.test.ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.10.0","axios":"^1.7.0","html-to-text":"^9.0.0","zod":"^3.23.0"},"devDependencies":{"@types/html-to-text":"^9.0.4","@types/node":"^20.12.0","tsx":"^4.7.0","typescript":"^5.4.0"},"engines":{"node":">=18.0.0"},"keywords":["mcp","freescout","claude","helpdesk"],"license":"MIT","gitHead":"7961e18b2d2e3d7ffd477c8c5f34dccda3b99f0a","_id":"@aurbi/mcp-ro-freescout@1.0.0","_nodeVersion":"25.8.2","_npmVersion":"11.12.1","dist":{"integrity":"sha512-qUbjFOHAO4TzUJMLhqL1a/jLHP/hkWtwoZ6SjRIDnHNa449xZF1GTFAEPrBTPu/sI5UOW8g0t60FUcLE9EsbMg==","shasum":"9754a8a968a849cc05ca809d1d23afbdeac4247e","tarball":"https://registry.npmjs.org/@aurbi/mcp-ro-freescout/-/mcp-ro-freescout-1.0.0.tgz","fileCount":33,"unpackedSize":85175,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHMZeYdMPcD8OYCdIbCUH9OhpLjg+mARXKhNcgZidKDMAiA3iB+aKNmao62iA/G/OJSrFdtww30ian3WvLHgAkvPaw=="}]},"_npmUser":{"name":"aurbi","email":"npm@arbi.in"},"directories":{},"maintainers":[{"name":"aurbi","email":"npm@arbi.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-ro-freescout_1.0.0_1777587929556_0.535301561846155"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T22:25:29.477Z","1.0.0":"2026-04-30T22:25:29.691Z","modified":"2026-04-30T22:25:29.880Z"},"maintainers":[{"name":"aurbi","email":"npm@arbi.in"}],"description":"read-only MCP server for FreeScout helpdesk — insight generation via Claude","keywords":["mcp","freescout","claude","helpdesk"],"license":"MIT","readme":"# @aurbi/mcp-ro-freescout\n\nread-only MCP server for FreeScout helpdesk.\n\nConnect Claude to your FreeScout helpdesk. Ask Claude questions about your support\nconversations, customers, and mailboxes — no coding required.\n\n---\n\n## Prerequisites\n\n**Node.js** must be installed on your computer.\n\n1. Go to [https://nodejs.org](https://nodejs.org)\n2. Click the **LTS** download button (the left one — it says \"Recommended for most users\")\n3. Run the installer and accept all defaults\n4. When it finishes, close and reopen any windows you have open\n\nThat's it. You do not need to understand what Node.js is — it just needs to be installed.\n\n---\n\n## Get your FreeScout API key\n\n1. Log in to your FreeScout instance as an administrator\n2. Click **Manage** in the top navigation bar\n3. Go to **Settings → API & Webhooks**\n4. Copy the API key shown on that page\n\nKeep this key handy — you'll paste it into the config file below.\n\n---\n\n## Installation (Claude Desktop on Windows)\n\nThere is no installer to run. You just edit one config file and restart Claude.\n\n### Step 1 — Find the config file\n\nOpen **File Explorer** and paste this into the address bar at the top, then press Enter:\n\n```\n%APPDATA%\\Claude\n```\n\nYou should see a file called `claude_desktop_config.json`. If that folder or file\ndoes not exist yet, open Claude Desktop at least once first, then try again.\n\n### Step 2 — Edit the config file\n\nRight-click `claude_desktop_config.json` and open it with **Notepad** (or any text editor).\n\nIf the file is empty or contains only `{}`, replace everything with the block below.\n\nIf the file already has content (other MCP servers), add the `\"freescout\"` section\ninside the existing `\"mcpServers\"` object — do not replace the whole file.\n\n```json\n{\n  \"mcpServers\": {\n    \"freescout\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aurbi/mcp-ro-freescout\"],\n      \"env\": {\n        \"FREESCOUT_BASE_URL\": \"https://your-freescout-instance.com\",\n        \"FREESCOUT_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nReplace:\n- `https://your-freescout-instance.com` with the URL you use to access FreeScout\n- `your_api_key_here` with the API key you copied in the previous section\n\n### Step 3 — Save and restart\n\nSave the file, then fully quit and reopen Claude Desktop.\n\n### Step 4 — Verify it works\n\nIn a new Claude conversation, type:\n\n> List my FreeScout mailboxes\n\nClaude should respond with a list of your mailboxes. If it does, everything is working.\n\n---\n\n## What Claude can do with this\n\nOnce connected, you can ask Claude things like:\n\n- \"Show me all open conversations in the Support mailbox\"\n- \"Summarize the last 10 conversations tagged 'billing'\"\n- \"Find conversations from customer@example.com\"\n- \"What's the full thread for conversation #482?\"\n- \"List unassigned conversations updated in the last 7 days\"\n\n---\n\n## Available tools\n\nThese are the actions Claude can take on your behalf. You don't need to call them\ndirectly — Claude picks the right one based on what you ask.\n\n| Tool | What it does |\n|------|-------------|\n| `list_conversations` | Browse conversations with official filters (`mailboxId`, `folderId`, `status`, `tag`, `assignedTo`, `createdSince`, `updatedSince`, `number`, `pageSize`) |\n| `get_conversation` | Fetch a single conversation by ID |\n| `search_conversations` | Search conversations with advanced `query` support where your FreeScout version documents it |\n| `get_conversation_with_threads` | Fetch a conversation plus its full message thread via dedicated GET, with 405 fallback to embedded threads |\n| `get_threads` | Fetch just the messages for a conversation via dedicated GET, with 405 fallback to embedded threads |\n| `list_customers` | Browse or search customer records with filters like `mailbox`, `firstName`, `lastName`, `modifiedSince`, `sortField`, `sortOrder`, `query`, `page` |\n| `get_customer` | Fetch a single customer by ID |\n| `list_mailboxes` | List all mailboxes (useful for finding mailbox IDs) |\n| `list_folders` | List folders within a mailbox (inbox, mine, closed, etc.) |\n| `list_users` | List agents/users, optionally filtered by mailbox |\n| `get_current_user` | Identify the agent associated with the configured API key |\n\n**Note:** This is a read-only connection. Claude can view your FreeScout data but\ncannot create, edit, or delete anything.\n\n---\n\n## Troubleshooting\n\n### Claude says it doesn't know about FreeScout tools\n\n- Double-check that you saved `claude_desktop_config.json` after editing it\n- Make sure you fully quit and reopened Claude Desktop (not just closed the window)\n- Check that the JSON in the config file is valid — every `{` must have a matching `}`,\n  every line except the last in a block must end with a comma\n\n### \"API key is invalid or missing\" error\n\n- Re-copy your API key from FreeScout (Manage → Settings → API & Webhooks)\n- Make sure there are no extra spaces before or after the key in the config file\n\n### \"Could not connect to FreeScout\" or network error\n\n- Check that `FREESCOUT_BASE_URL` is the exact URL you use to open FreeScout in a browser\n- Include `https://` at the start; do not include a trailing `/`\n- Confirm your FreeScout instance is reachable from your computer\n\n### The config file doesn't exist\n\nOpen Claude Desktop, wait for it to load fully, then close it. The config folder\nshould now exist. If it still doesn't, check that Claude Desktop is installed and\nhas been opened at least once.\n\n### Thread reads return 405\n\nSome older or mismatched FreeScout API modules return 405 for the documented\nthread route. These tools fall back from `GET /conversations/{id}/threads` to\n`GET /conversations/{id}?embed=threads`. If both paths fail, compare your\ninstance `/api/docs` with the installed API & Webhooks module version.\n\n### Validating your JSON\n\nIf you're unsure whether your config file is valid JSON, paste it into\n[https://jsonlint.com](https://jsonlint.com) — it will highlight any errors.\n\n---\n\n## For developers\n\n```bash\n# clone and install\ngit clone https://github.com/aurbi/mcp-ro-freescout\ncd mcp-ro-freescout\nnpm install\n\n# run in dev mode (uses tsx, reads .env)\ncp .env.example .env   # fill in your values\nnpm run dev\n\n# test and build\nnpm test\nnpm run build\n```\n\nRequires Node.js >= 18. Written in TypeScript; compiled output in `dist/`.\nSee `docs/specs/mcp-server-design.md` for architecture details.\n","readmeFilename":"README.md","_rev":"1-f26c3147edfff1272be722fa0280e088"}