# Clay.com MCP Server

MCP (Model Context Protocol) server for Clay.com API integration, providing people and company enrichment tools.

## Features

- **People Search & Enrichment**: Find and enrich people by title, company, industry, location
- **Company Search & Enrichment**: Find and enrich companies by industry, technology, funding, size
- **Clay Tables**: List, query, and explore your Clay workspace tables

## Installation

```bash
npm install @civic-wisdom/clay-mcp
```

Or clone and build from source:

```bash
git clone https://github.com/bpw-civic/clay-mcp-server.git
cd clay-mcp-server
npm install
npm run build
```

## Configuration

Set your Clay API key as an environment variable:

```bash
export CLAY_API_KEY=your-api-key-here
```

## Usage

### With Claude Code

Add to your `.claude/settings.json` or `.mcp.json`:

```json
{
  "mcpServers": {
    "clay": {
      "command": "node",
      "args": ["node_modules/@civic-wisdom/clay-mcp/dist/index.js"],
      "env": {
        "CLAY_API_KEY": "${CLAY_API_KEY}"
      }
    }
  }
}
```

Or if installed from source:

```json
{
  "mcpServers": {
    "clay": {
      "command": "node",
      "args": ["/path/to/clay-mcp-server/dist/index.js"],
      "env": {
        "CLAY_API_KEY": "${CLAY_API_KEY}"
      }
    }
  }
}
```

### With Other MCP Clients

The server communicates via stdio. Start it with:

```bash
CLAY_API_KEY=your-key node dist/index.js
```

## Available Tools

### People Tools

#### `clay_search_people`
Search for people matching specific criteria.

**Parameters:**
- `query` (string, optional): Natural language search query
- `filters` (object, optional):
  - `titles`: Array of job titles
  - `companies`: Array of company names
  - `industries`: Array of industries
  - `locations`: Array of locations
  - `companySize`: Company size range (e.g., "51-200")
  - `seniorityLevels`: Array of seniority levels
- `limit` (number, default 25): Maximum results

**Example:**
```json
{
  "query": "ML engineers",
  "filters": {
    "industries": ["Technology", "AI"],
    "companySize": "51-200"
  },
  "limit": 10
}
```

#### `clay_enrich_person`
Get full enrichment data for a specific person.

**Parameters (at least one required):**
- `email`: Email address
- `linkedinUrl`: LinkedIn profile URL
- `fullName` + `company`: Name and company combo

**Example:**
```json
{
  "email": "jane@example.com"
}
```

**Returns:**
- Full name, title, company
- Work experience history
- Education
- Skills
- Social profiles (LinkedIn, Twitter, GitHub)
- Location details
- Contact information

### Company Tools

#### `clay_search_companies`
Search for companies matching specific criteria.

**Parameters:**
- `query` (string, optional): Natural language search query
- `filters` (object, optional):
  - `industries`: Array of industries
  - `technologies`: Array of technologies
  - `employeeCount`: Size range (e.g., "51-200")
  - `fundingStage`: Funding stage (e.g., "series_a")
  - `location`: Location string
  - `foundedAfter`: Year (number)
  - `foundedBefore`: Year (number)
- `limit` (number, default 25): Maximum results

**Example:**
```json
{
  "filters": {
    "industries": ["AI", "Machine Learning"],
    "fundingStage": "series_a",
    "location": "San Francisco"
  }
}
```

#### `clay_enrich_company`
Get full enrichment data for a specific company.

**Parameters (at least one required):**
- `domain`: Company domain
- `name`: Company name
- `linkedinUrl`: Company LinkedIn URL

**Example:**
```json
{
  "domain": "anthropic.com"
}
```

**Returns:**
- Company name, domain, description
- Industry classification
- Employee count and range
- Founding year
- Location details
- Funding information (total raised, last round, investors)
- Technographics (technologies used)
- Social profiles
- Recent news

### Table Tools

#### `clay_list_tables`
List all Clay tables in your workspace.

**Parameters:** None

**Returns:** List of tables with ID, name, description, row count, and timestamps.

#### `clay_get_table_schema`
Get the schema for a specific table.

**Parameters:**
- `tableId` (required): Table ID

**Returns:** Table metadata and column definitions (name, type, description).

#### `clay_query_table`
Query a Clay table with filters.

**Parameters:**
- `tableId` (required): Table ID
- `filters` (object, optional): Filter conditions
- `sort` (object, optional): Sort configuration
  - `column`: Column name
  - `order`: "asc" or "desc"
- `limit` (number, default 50): Maximum results
- `offset` (number, default 0): Pagination offset

**Example:**
```json
{
  "tableId": "tbl_abc123",
  "filters": { "status": "active" },
  "sort": { "column": "created_at", "order": "desc" },
  "limit": 25
}
```

## Resources

The server exposes Clay tables as MCP resources:

- `clay://tables` - List all tables
- `clay://tables/{id}/schema` - Table schema

## Development

```bash
# Install dependencies
npm install

# Watch mode (rebuild on changes)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run the server
npm start
```

## Error Handling

The server handles:
- **Rate limiting** (429 responses) with retry information
- **API errors** with descriptive messages
- **Missing authentication** with clear error message
- **Invalid parameters** with validation feedback

## Requirements

- Node.js 18+
- Clay.com API key ([Get one here](https://app.clay.com/settings/api))

## API Reference

This server uses the Clay.com REST API:
- Base URL: `https://api.clay.com/v1`
- Authentication: API key in `X-Api-Key` header

For Clay.com API documentation, visit: https://docs.clay.com/api

## License

MIT License - see [LICENSE](LICENSE) file.