README.md•7.53 kB
# Fathom MCP Server
A Model Context Protocol (MCP) server that provides AI agents with access to Fathom AI meeting data, including transcripts, summaries, teams, and team members.
## Features
This MCP server exposes 5 tools for interacting with Fathom AI:
- **`fathom_list_meetings`** - List meetings with optional filters (date ranges, invitees, teams, etc.)
- **`fathom_get_summary`** - Get meeting summary by recording ID
- **`fathom_get_transcript`** - Get meeting transcript with speaker information and timestamps
- **`fathom_list_teams`** - List all teams in the organization
- **`fathom_list_team_members`** - List team members for a specific team
## Architecture
- **Framework**: Next.js 15 with App Router
- **MCP Adapter**: [mcp-handler](https://www.npmjs.com/package/mcp-handler) (Vercel's official MCP adapter)
- **Transport**: Supports both Streamable HTTP and Server-Sent Events (SSE)
- **Deployment**: Vercel with automatic HTTPS and global CDN
- **Type Safety**: Full TypeScript support with Zod validation
## Quick Start
### 1. Clone and Install
```bash
git clone <your-repo-url>
cd fathom-mcp-server
npm install
```
### 2. Environment Setup
Copy the environment template and add your Fathom API key:
```bash
cp .env.example .env.local
```
Edit `.env.local`:
```
FATHOM_API_KEY=your_fathom_api_key_here
```
Get your API key from [Fathom Settings](https://app.fathom.video/settings/api).
### 3. Local Development
```bash
npm run dev
```
The MCP server will be available at `http://localhost:3000/api/mcp`
### 4. Deploy to Vercel
[](https://vercel.com/new/clone?repository-url=https://github.com/your-username/fathom-mcp-server)
Or deploy manually:
```bash
npm install -g vercel
vercel
```
Add your `FATHOM_API_KEY` environment variable in the Vercel dashboard.
## Client Integration
### OpenAI AgentKit
Connect directly to the HTTP endpoint with Bearer token authentication:
```json
{
"mcpServers": {
"fathom": {
"url": "https://fathom-mcp.vercel.app/api/mcp",
"auth": {
"type": "bearer",
"token": "YOUR_FATHOM_API_KEY"
}
}
}
}
```
**Configuration Steps:**
1. Replace `YOUR_FATHOM_API_KEY` with your actual Fathom AI API key
2. The API key is passed as a Bearer token in the Authorization header
3. This keeps the API key client-side controlled and secure
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"fathom": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://fathom-mcp.vercel.app/api/mcp"
]
}
}
}
```
**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
### Cursor
Add to your `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"fathom": {
"url": "https://your-app.vercel.app/api/mcp"
}
}
}
```
## Tool Usage Examples
### List Recent Meetings
```json
{
"name": "fathom_list_meetings",
"arguments": {
"created_after": "2024-01-01T00:00:00Z",
"include_summary": true,
"limit": 10
}
}
```
### Get Meeting Transcript
```json
{
"name": "fathom_get_transcript",
"arguments": {
"recording_id": 123456789
}
}
```
### Filter Meetings by Team
```json
{
"name": "fathom_list_meetings",
"arguments": {
"teams": ["Engineering", "Product"],
"include_action_items": true
}
}
```
### List Team Members
```json
{
"name": "fathom_list_team_members",
"arguments": {
"team_id": "team_123"
}
}
```
## API Reference
### fathom_list_meetings
List meetings with optional filters.
**Parameters:**
- `calendar_invitees` (string[]): Email addresses to filter by
- `calendar_invitees_domains` (string[]): Company domains to filter by
- `calendar_invitees_domains_type` (enum): Filter by external domains
- `created_after` (string): ISO 8601 timestamp
- `created_before` (string): ISO 8601 timestamp
- `include_transcript` (boolean): Include transcript data
- `include_summary` (boolean): Include summary data
- `include_action_items` (boolean): Include action items
- `include_crm_matches` (boolean): Include CRM matches
- `limit` (number): Max results (1-100)
- `cursor` (string): Pagination cursor
- `recorded_by` (string[]): Filter by recorder emails
- `teams` (string[]): Filter by team names
### fathom_get_summary
Get meeting summary by recording ID.
**Parameters:**
- `recording_id` (number): The recording ID
### fathom_get_transcript
Get meeting transcript with speaker information.
**Parameters:**
- `recording_id` (number): The recording ID
### fathom_list_teams
List all teams in the organization.
**Parameters:**
- `cursor` (string): Optional pagination cursor
### fathom_list_team_members
List team members for a specific team.
**Parameters:**
- `team_id` (string): The team ID
- `cursor` (string): Optional pagination cursor
## Error Handling
The server includes comprehensive error handling:
- **Missing API Key**: Clear error message if `FATHOM_API_KEY` is not set
- **Fathom API Errors**: Properly formatted error responses with status codes
- **Rate Limiting**: Graceful handling of 429 responses
- **Input Validation**: Zod schemas validate all tool inputs
- **Network Errors**: Timeout and connection error handling
## Security Considerations
- **HTTPS Only**: Vercel provides automatic TLS certificates
- **CORS Headers**: Configured for OpenAI's infrastructure
- **API Key Security**: Stored in environment variables, never committed
- **Input Validation**: All inputs validated with Zod schemas
- **Rate Limiting**: Respects Fathom API rate limits
## Development
### Project Structure
```
├── app/
│ └── api/
│ └── [transport]/
│ └── route.ts # MCP route handler
├── lib/
│ └── fathom-client.ts # Fathom API client
├── .env.example # Environment template
├── vercel.json # Vercel configuration
└── README.md # This file
```
### Testing
Test the MCP server locally:
```bash
# Start the development server
npm run dev
# Test with curl
curl -X POST http://localhost:3000/api/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'
```
### Type Checking
```bash
npm run type-check
```
## Troubleshooting
### Common Issues
1. **"FATHOM_API_KEY environment variable is required"**
- Ensure you've set the environment variable in `.env.local` (local) or Vercel dashboard (production)
2. **"Fathom API Error (401)"**
- Check that your API key is valid and has the correct permissions
3. **"Fathom API Error (429)"**
- You've hit Fathom's rate limit. Wait before making more requests
4. **CORS errors in browser**
- The server includes proper CORS headers. If issues persist, check your client configuration
### Debug Mode
Enable verbose logging in development:
```bash
NODE_ENV=development npm run dev
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
- **Fathom API Documentation**: [developers.fathom.ai](https://developers.fathom.ai)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Issues**: Create an issue in this repository