Fullstory MCP Server

An MCP (Model Context Protocol) server that connects Claude to your Fullstory analytics data. Once configured, you and your team can ask Claude questions about user sessions, events, segments, and more.

Features

| Tool | Description | |------|-------------| | fullstory_get_user_sessions | Get session replays for a user | | fullstory_get_session_replay_url | Get direct URL to watch a session | | fullstory_get_user | Get user details and properties | | fullstory_search_users | Search users by email, name, or custom properties | | fullstory_get_user_events | Get events for a user within a time range | | fullstory_list_segments | List all saved segments | | fullstory_export_segment | Export segment data (users or events) | | fullstory_get_export_status | Check export job progress | | fullstory_download_export | Download completed export data | | fullstory_send_event | Send custom events to Fullstory |

Prerequisites

• Node.js 18+
• Fullstory account with API access
• Admin or Architect API key (for full functionality)

Quick Start

1. Clone and Install

cd fullstory-mcp-server
npm install

2. Configure Environment

cp .env.example .env

Edit .env and add your Fullstory API key:

FULLSTORY_API_KEY=your_api_key_here
FULLSTORY_DATA_CENTER=na1

Getting your API key:

1. Log into Fullstory
2. Go to Settings → API Keys
3. Create a new key with Admin or Architect role
4. Copy the key (you won't be able to see it again)

3. Build

npm run build

4. Test Locally

npm start

Deployment Options

Option A: Shared Server (Recommended for Teams)

Deploy to a cloud server so all team members can use the same connection.

Using Docker

# Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
ENV NODE_ENV=production
CMD ["node", "dist/index.js"]

docker build -t fullstory-mcp-server .
docker run -d \
  -e FULLSTORY_API_KEY=your_key \
  -e FULLSTORY_DATA_CENTER=na1 \
  --name fullstory-mcp \
  fullstory-mcp-server

Using PM2 (on a Linux server)

npm install -g pm2
pm2 start dist/index.js --name fullstory-mcp
pm2 save
pm2 startup

Option B: Local Machine (Per User)

Each team member runs the server on their own machine.

Connecting to Claude

For Claude Desktop App

Add to your Claude configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fullstory": {
      "command": "node",
      "args": ["/path/to/fullstory-mcp-server/dist/index.js"],
      "env": {
        "FULLSTORY_API_KEY": "your_api_key_here",
        "FULLSTORY_DATA_CENTER": "na1"
      }
    }
  }
}

For Remote/Shared Server

If running on a shared server, configure the connection URL in your MCP client settings.

Usage Examples

Once connected, you can ask Claude things like:

• "Show me the recent sessions for user [email protected]"
• "What events did user 12345 trigger last week?"
• "List all our Fullstory segments"
• "Export the 'Power Users' segment as CSV"
• "Get me the replay URL for session abc123"

API Key Permissions

| Feature | Required Role | |---------|---------------| | Sessions, Users, Events | Normal, Admin, Architect | | Segment Exports | Admin, Architect | | Audit Trails | Admin, Architect |

Troubleshooting

"Authentication failed"

• Check that your API key is correct
• Ensure the key hasn't been revoked
• Verify the data center setting matches your account

"Rate limit exceeded"

• Segment exports are limited to 2 requests/minute
• Wait before making additional requests

"Access forbidden"

• Your API key may not have sufficient permissions
• Upgrade to Admin or Architect role for full access

Security Notes

• Store API keys securely (use environment variables, not hardcoded values)
• Rotate API keys periodically
• Use the minimum required permission level
• For team deployments, consider using a dedicated service account

Contributing

Feel free to extend this server with additional Fullstory API endpoints as needed.

License

MIT