IMRA Data Service MCP Server

A Model Context Protocol (MCP) server that exposes the Insightology IMRA (Interview Management and Research Analysis) Data Service API as tools. It lets AI assistants (e.g. Cursor) manage organisations, clients, projects, briefs, interviews, discussion guides, spend data, and analyzer runs through a single MCP interface.

Features

This MCP server provides read, list, create, update, and delete tools for every domain entity:

• Get-by-ID tools – Fetch a single resource by ID (brief, project, client, organisation, interview, interview guide, interview session, interview invitation, discussion guide, organisation member, organisation invitation, analyzer run, analyzer run file/response/conversation/insight, spend, brief source).
• List tools – List resources by parent (e.g. briefs by project, interviews by project, clients by organisation, projects by organisation or client, discussion guides by project or brief, etc.).
• Special list tools – list_organisations, list_interviews_open_to_all, list_briefs (with pagination), search_projects_by_organisation_and_client.
• Create / update / delete tools – Named tools for each entity (e.g. create_brief, update_brief, delete_brief; create_project, update_project, delete_project; and so on for organisation, client, brief source, spend, discussion guide, interview guide, interview, interview session, interview invitation, analyzer run, analyzer run file/response/conversation/insight).

Responses are returned as markdown with JSON where applicable.

Installation

npm install

Building

npm run build

This compiles TypeScript with tsc and writes output to dist/. Use this before running the server or publishing.

Development

# Build the project
npm run build

# Run the compiled server (requires base URL)
node dist/index.js <imra-data-service-url> [api-key]

# Or run from source with tsx
npm run dev

Note: npm run dev runs tsx src/index.ts without arguments; you must configure the IMRA base URL via config or pass it when invoking the server (e.g. in Cursor MCP args).

Usage with npx

After building and publishing to npm:

npx @insightology.ai/imra-data-service-mcp <imra-data-service-url> [api-key]

Examples:

# Without API key
npx @insightology.ai/imra-data-service-mcp http://localhost:3000

# With API key
npx @insightology.ai/imra-data-service-mcp http://localhost:3000 your-api-key

Command-line arguments

• <imra-data-service-url> (required): Base URL of the IMRA Data Service (e.g. http://localhost:3000). Paths such as /api/brief, /api/project, etc. are appended to this URL.
• [api-key] (optional): API key sent in the X-API-Key header when provided.

Paths are automatically prefixed with /api. For example, with base URL http://localhost:3000, a request to the brief resource uses http://localhost:3000/api/brief.

Adding to Cursor

1. Open Settings → Features → Model Context Protocol → Servers.
2. Add a server entry, for example:

{
  "mcpServers": {
    "imra-data-service": {
      "command": "npx",
      "args": [
        "@insightology.ai/imra-data-service-mcp",
        "http://localhost:3000"
      ]
    }
  }
}

Replace http://localhost:3000 with your IMRA Data Service URL. If the service requires an API key, add it as the third element in args or use env (see below).

Using environment variables

To avoid putting the URL or API key in the config file:

{
  "mcpServers": {
    "imra-data-service": {
      "command": "npx",
      "args": ["@insightology.ai/imra-data-service-mcp"],
      "env": {
        "imra-data-service__url": "http://localhost:3000",
        "imra-data-service__apiKey": "your-api-key-here"
      }
    }
  }
}

3. Restart Cursor so the MCP server loads.

MCP tools overview

Read, list, create, update, and delete are exposed as separate named tools per entity.

Get-by-ID tools

Return a single resource by ID:

get_brief, get_project, get_client, get_organisation, get_interview, get_interview_guide, get_interview_session, get_interview_invitation, get_discussion_guide, get_organisation_member, get_organisation_invitation, get_analyzer_run, get_analyzer_run_file, get_analyzer_run_response, get_analyzer_run_conversation, get_analyzer_run_insight, get_spend, get_brief_source.

Each takes a single argument (e.g. id for the resource ID).

List-by-parent tools

Return a list of resources for a given parent:

| Tool | Parent parameter | |------|-------------------| | get_briefs_by_project | projectId | | list_interviews_by_project | projectId | | list_interview_guides_by_project | projectId | | list_interview_sessions_by_interview | interviewId | | list_interview_sessions_by_user | userId | | list_interview_invitations_by_interview | interviewId | | list_interview_invitations_by_user_token | userToken | | list_discussion_guides_by_project | projectId | | list_discussion_guides_by_brief | briefId | | list_clients_by_organisation | organisationId | | list_projects_by_organisation | organisationId | | get_projects_by_client | clientId | | list_organisation_members_by_organisation | organisationId | | list_organisation_members_by_user | userId | | list_organisation_invitations_by_organisation | organisationId | | list_organisation_invitations_by_email | email | | list_spend_by_project | projectId | | list_analyzer_runs_by_project | projectId | | list_analyzer_run_files_by_analyzer_run | analyzerRunId | | list_analyzer_run_responses_by_analyzer_run | analyzerRunId | | list_analyzer_run_conversations_by_analyzer_run | analyzerRunId | | list_analyzer_run_insights_by_conversation | analyzerRunConversationId | | list_brief_sources_by_brief | briefId |

Other list / search tools

| Tool | Description | |------|-------------| | list_organisations | GET all organisations (no parameters). | | list_interviews_open_to_all | GET interviews that are open to all (no parameters). | | list_briefs | List briefs with optional userId, limit, offset, sortBy, sortOrder. | | search_projects_by_organisation_and_client | POST search: organisationIds (required), optional clientId, tag, limit, offset, orderBy, orderDirection. |

Create / update / delete tools

Each domain entity has dedicated tools:

• Organisation: create_organisation, update_organisation, delete_organisation
• Organisation member: create_organisation_member, update_organisation_member, delete_organisation_member
• Organisation invitation: create_organisation_invitation, update_organisation_invitation, delete_organisation_invitation
• Client: create_client, update_client, delete_client
• Project: create_project, update_project, delete_project
• Brief: create_brief, update_brief, delete_brief
• Brief source: create_brief_source, update_brief_source, delete_brief_source
• Spend: create_spend, update_spend, delete_spend
• Discussion guide: create_discussion_guide, update_discussion_guide, delete_discussion_guide
• Interview guide: create_interview_guide, update_interview_guide, delete_interview_guide
• Interview: create_interview, update_interview, delete_interview
• Interview session: create_interview_session, update_interview_session, delete_interview_session
• Interview invitation: create_interview_invitation, update_interview_invitation, delete_interview_invitation
• Analyzer run: create_analyzer_run, update_analyzer_run, delete_analyzer_run
• Analyzer run file: create_analyzer_run_file, update_analyzer_run_file, delete_analyzer_run_file (use isSpss as string "true" or "false")
• Analyzer run response: create_analyzer_run_response, update_analyzer_run_response, delete_analyzer_run_response
• Analyzer run conversation: create_analyzer_run_conversation, update_analyzer_run_conversation, delete_analyzer_run_conversation
• Analyzer run insight: create_analyzer_run_insight, update_analyzer_run_insight, delete_analyzer_run_insight

Each create/update tool takes a schema matching the API body (see server instructions or API docs for required and optional fields).

Local development with npx

npm run build
npm link
npx @insightology.ai/imra-data-service-mcp http://localhost:3000

Publishing

npm login
npm publish --access public

License

Apache-2.0