@gongrzhe/server-fireflies-mcp/README.md

MCP server for using the Fireflies.ai API with session-aware multi-user support

# Fireflies MCP Server

A stateless Model Context Protocol (MCP) server for the Fireflies.ai API, enabling transcript retrieval, search functionality, and summary generation.

## Features

- **Stateless Architecture**: Complete request isolation with no session management overhead
- **Bearer Token Authentication**: Standard Authorization header support for secure API access
- **Fresh Instance Per Request**: Each request gets a new server instance for complete isolation
- **Advanced Search**: Search through meeting transcripts by keywords with date filtering
- **Summary Generation**: Generate formatted summaries in bullet points or paragraph format
- **Comprehensive Error Handling**: Clear error messages for common issues
- **Timeout Resilience**: Automatic fallback to minimal data on API timeouts

## Quick Start

### Starting the Server

```bash
# Start stateless HTTP server on port 30000 (default)
node dist/index.js

# Start HTTP server on custom port
PORT=8080 node dist/index.js
```

The server provides these endpoints:
- **`POST /mcp`** - Main MCP endpoint (stateless mode)
- **`GET|DELETE /mcp`** - Disabled (returns 405 Method Not Allowed)

### Authentication

All requests require a Fireflies API Token via Authorization header:

```bash
Authorization: Bearer your_fireflies_api_token_here
```

[Create a Fireflies API Key](https://fireflies.ai/dashboard/settings/api) from your Fireflies dashboard under Settings > API.

## Tools

The server provides 4 tools for comprehensive Fireflies API access. Each tool requires `Authorization: Bearer <token>` header.

### 1. fireflies_get_transcripts
Retrieve a list of meeting transcripts with optional filtering.

```bash
curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_fireflies_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "fireflies_get_transcripts",
      "arguments": {
        "limit": 10,
        "from_date": "2024-01-01",
        "to_date": "2024-12-31"
      }
    }
  }'
```

### 2. fireflies_get_transcript_details
Get detailed information about a specific transcript including full conversation and metadata.

```bash
curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_fireflies_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "fireflies_get_transcript_details",
      "arguments": {
        "transcript_id": "transcript_abc123"
      }
    }
  }'
```

### 3. fireflies_search_transcripts
Search for transcripts containing specific keywords with optional date filtering.

```bash
curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_fireflies_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "fireflies_search_transcripts",
      "arguments": {
        "query": "project planning",
        "limit": 5,
        "from_date": "2024-01-01",
        "to_date": "2024-12-31"
      }
    }
  }'
```

### 4. fireflies_generate_summary
Generate a formatted summary of a meeting transcript.

```bash
curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_fireflies_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "fireflies_generate_summary",
      "arguments": {
        "transcript_id": "transcript_abc123",
        "format": "bullet_points"
      }
    }
  }'
```

## List Available Tools

Get the complete list of available tools:

```bash
curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_fireflies_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'
```

## Authentication Setup

### Fireflies API Key
[Create a Fireflies API Key](https://fireflies.ai/dashboard/settings/api) with appropriate permissions:
- Go to [Fireflies Dashboard](https://fireflies.ai/dashboard/settings/api)  
- Navigate to Settings > API
- Generate a new API key
- Copy the generated key for use in Authorization headers

## Usage with Claude Desktop

### NPX
```json
{
  "mcpServers": {
    "fireflies": {
      "command": "npx",
      "args": [
        "-y",
        "@gongrzhe/server-fireflies-mcp"
      ],
      "env": {
        "FIREFLIES_API_KEY": "<YOUR_TOKEN>"
      }
    }
  }
}
```

### Local Development
```json
{
  "mcpServers": {
    "fireflies": {
      "command": "node",
      "args": [
        "/path/to/fireflies-mcp/dist/index.js"
      ],
      "env": {
        "FIREFLIES_API_KEY": "<YOUR_TOKEN>"
      }
    }
  }
}
```

## Installation

### Option 1: Using npx (Recommended)
```bash
npx @gongrzhe/server-fireflies-mcp
```

### Option 2: Global Installation
```bash
npm install -g @gongrzhe/server-fireflies-mcp
fireflies-mcp
```

### Option 3: Development Setup
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```

## Build

Build the project:
```bash
npm run build
```

## Health Check

Check if the server is running:
```bash
curl http://localhost:30000/health
```

Returns:
```json
{
  "status": "ok",
  "server": "Fireflies MCP Server (Stateless)",
  "timestamp": "2024-12-19T12:00:00.000Z",
  "version": "1.0.0",
  "sessionIsolation": false,
  "stateless": true
}
```

## Migration from Session-Aware Version

### Breaking Changes
1. **Authentication**: Now uses `Authorization: Bearer <token>` headers instead of custom headers
2. **Port**: Default port changed from 3000 to 30000  
3. **Session Management**: No longer supported (stateless mode only)
4. **Endpoints**: Only POST /mcp is supported
5. **Transport**: HTTP mode only, no STDIO or SSE support

### Migration Steps
1. Update client code to use Bearer tokens in Authorization headers
2. Change default port to 30000 in configurations
3. Remove any session management code from client implementations
4. Update error handling for stateless responses

## Benefits of Stateless Architecture

### Scalability
- **Horizontal Scaling**: Easy to load balance across multiple instances
- **No State Synchronization**: No need to share state between instances  
- **Resource Efficiency**: Memory usage scales linearly with concurrent requests

### Security
- **No Token Storage**: Tokens are never cached or stored server-side
- **Request Isolation**: Complete separation between user requests
- **Fresh Validation**: Each request validates tokens independently

### Reliability
- **Fault Tolerance**: Request failures don't affect other operations
- **No Memory Leaks**: Automatic cleanup after each request
- **Simplified Debugging**: Each request is independent and traceable

## License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.