# Attio MCP Server

A Model Context Protocol (MCP) server for Attio, the AI-native CRM. This server enables AI assistants like Claude to interact directly with your Attio data, providing seamless integration between conversational AI and your CRM workflows.

## Features

### 🏢 **Company Management**
- **Smart Search**: Find companies with complex filters and sorting
- **Full CRUD**: Create, read, update company records
- **Rich Attributes**: Support for domains, industry, employee count, and more

### 👥 **People Management**
- **Contact Search**: Find people by email, phone, job title, and other attributes
- **Contact Management**: Create and update person records
- **Social Integration**: LinkedIn, Twitter URL support
- **Multi-channel**: Email and phone number arrays

### 📋 **Task Management**
- **Task Creation**: Create tasks with deadlines and assignees
- **Task Filtering**: Filter by assignee, completion status, linked records
- **Record Linking**: Connect tasks to companies, people, or other objects
- **Assignment**: Assign tasks to workspace members

### 📝 **Notes Management**
- **Rich Notes**: Create detailed notes with titles and content
- **Record Association**: Attach notes to any record type
- **Organization**: Filter notes by parent object or record

### 📑 **List Management**
- **List Discovery**: Find all lists or filter by object type
- **Entry Management**: Add/remove records from lists
- **Bulk Operations**: Manage multiple list entries efficiently

## Installation

### Prerequisites
- Node.js 18+ 
- Attio API Key ([Get one here](https://developers.attio.com/))

### Setup

1. **Clone or create the project directory:**
```bash
mkdir attio-mcp-server
cd attio-mcp-server
```

2. **Create the package.json, tsconfig.json, and source files** using the provided code artifacts.

3. **Install dependencies:**
```bash
npm install
```

4. **Build the project:**
```bash
npm run build
```

5. **Set up your Attio API key:**
```bash
export ATTIO_API_KEY="your_api_key_here"
```

## Configuration

### Claude Desktop Integration

Add this to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "attio": {
      "command": "node",
      "args": ["/path/to/your/attio-mcp-server/dist/index.js"],
      "env": {
        "ATTIO_API_KEY": "your_attio_api_key_here"
      }
    }
  }
}
```

### Alternative: Global Installation

```bash
# Make it globally accessible
npm install -g .

# Then use in Claude config:
{
  "mcpServers": {
    "attio": {
      "command": "attio-mcp-server",
      "env": {
        "ATTIO_API_KEY": "your_attio_api_key_here"
      }
    }
  }
}
```

## Usage Examples

Once configured, you can ask Claude natural language questions about your Attio data:

### Company Operations
```
"Find all technology companies in our CRM"
"Show me companies with more than 100 employees"
"Create a new company record for Acme Corp with domain acme.com"
"Update Google's employee count to 150000"
```

### People Management
```
"Find all contacts at Microsoft"
"Show me people with email addresses containing @google.com"
"Create a contact for Sarah Johnson with email sarah@example.com"
"Add a phone number to John Doe's record"
```

### Task Management
```
"Show me all completed tasks"
"Create a task to follow up with Acme Corp next Friday"
"Find tasks assigned to john@company.com"
"Mark task as completed"
```

### Notes
```
"Add a note to Acme Corporation about our recent product demo"
"Show all notes for this company"
"Create a note about the meeting outcome"
```

### Lists
```
"Show me all prospect lists"
"Add this company to our Q1 outreach list"
"Remove this contact from the cold leads list"
```

## Available Tools

### Company Tools
- `search_companies` - Search companies with filters and sorting
- `get_company` - Get company details by ID
- `create_company` - Create new company record
- `update_company` - Update existing company

### People Tools
- `search_people` - Search people with filters and sorting
- `get_person` - Get person details by ID
- `create_person` - Create new person record
- `update_person` - Update existing person

### Task Tools
- `get_tasks` - Get tasks with optional filtering
- `create_task` - Create new task
- `update_task` - Update existing task

### Note Tools
- `get_notes` - Get notes with optional filtering
- `create_note` - Create new note

### List Tools
- `get_lists` - Get all lists or filter by object type
- `get_list_entries` - Get entries in a specific list
- `add_to_list` - Add record to list
- `remove_from_list` - Remove record from list

## Security Features

- ✅ **Secure API Authentication**: Industry-standard bearer token authentication
- ✅ **No Data Storage**: Direct API passthrough with no local data retention
- ✅ **Open Source**: Full transparency with all source code available
- ✅ **Error Handling**: Comprehensive error handling and validation
- ✅ **Type Safety**: Full TypeScript implementation with proper types

## Development

### Project Structure
```
attio-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── attio-client.ts   # Attio API client
│   └── types.ts          # TypeScript type definitions
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Scripts
```bash
npm run build    # Build TypeScript
npm run dev      # Watch mode for development
npm start        # Start the server
npm run lint     # Lint code
```

### API Integration

The server integrates with Attio's REST API v2, supporting:
- OAuth 2.0 authentication
- Full CRUD operations
- Advanced querying and filtering
- Pagination support
- Error handling and retry logic

## Troubleshooting

### Common Issues

1. **API Key Issues**
   - Ensure your API key is set in the environment
   - Verify the key has the required scopes in Attio

2. **Connection Issues**
   - Check your internet connection
   - Verify the Attio API is accessible

3. **Claude Integration**
   - Ensure the path to the compiled JavaScript is correct
   - Check that Node.js is in your PATH
   - Restart Claude Desktop after configuration changes

### Required Scopes

Your Attio API key needs these scopes:
- `record_permission:read` and `record_permission:read-write`
- `object_configuration:read`
- `list_entry:read` and `list_entry:read-write`
- `task:read` and `task:read-write`
- `note:read` and `note:read-write`
- `user_management:read`

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions:
1. Check the troubleshooting section
2. Review Attio's API documentation
3. Create an issue in this repository

---

**Ready to transform your CRM workflow?** Install this Attio MCP Server and experience the future of AI-powered customer relationship management!