# Abbe MCP Server

MCP (Model Context Protocol) server for the [Abbe Core API](https://abbeapi.com) — AI workforce impact analysis across 922 U.S. occupations.

Connects AI coding assistants (Claude Code, Claude Desktop, Cursor) to the hosted Abbe API. Runs locally, makes authenticated HTTP calls.

## Installation

```bash
pip install abbe-mcp
```

## Configuration

Set your API key as an environment variable or in your MCP config (see below):

```bash
export ABBE_API_KEY=your-api-key
```

`ABBE_API_URL` is optional — defaults to `https://abbeapi.com`.

## Setup

### Claude Code

```bash
claude mcp add abbe abbe-mcp -e ABBE_API_KEY=your-api-key
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "abbe": {
      "command": "abbe-mcp",
      "env": {
        "ABBE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "abbe": {
      "command": "abbe-mcp",
      "env": {
        "ABBE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `resolve_job_title` | Resolve a job title to a standardized O\*NET occupation code |
| `get_ai_impact` | Get AI impact scores (displacement/augmentation) for occupations |
| `analyze_workforce` | Analyze AI impact across a workforce portfolio with headcount and salary |
| `get_skills` | Get the most important and distinctive skills for occupations |
| `get_occupation_tasks` | Get task-level AI impact labels for a specific occupation |
| `list_occupations` | Browse and search the 922 scored occupations |
| `get_api_info` | Get API metadata, model version, and coverage statistics |

## Example Usage

Ask your AI assistant natural-language questions:

> "How will AI affect software engineers?"

> "Compare AI impact on nurses vs accountants"

> "Analyze a team of 50 software developers and 20 product managers"

> "What specific tasks are driving AI impact for Lawyers?"

The assistant resolves titles to SOC codes, fetches impact scores, and formats results automatically.

## API Documentation

- Interactive docs: https://abbeapi.com/docs
- Portal: https://abbeapi.com/portal

## Troubleshooting

**"ABBE_API_KEY environment variable is not set"** — Add your API key to the MCP config's `env` block.

**"Abbe API error (429)"** — Rate limit hit. The resolve endpoint allows 30 requests/min. Wait and retry.

**Tool not showing up** — Run `abbe-mcp` in your terminal. If it hangs waiting for stdin, the server is working (stdio transport). Press Ctrl+C to exit.

## License

MIT
