# CompanyData MCP server

Model Context Protocol server that exposes the [CompanyData HTTP API](https://companydata.com/api-docs/) as tools: **company search**, **company export (enrich)**, and **location lookup** (cities).

Product overview and setup guide: [companydata.com/product/mcp-server/](https://companydata.com/product/mcp-server/).

OpenAPI contract: [https://companydata.com/openapi.json](https://companydata.com/openapi.json).

## Hosted (no install)

Connect your MCP client to `https://companydata.com/mcp/` and send your API key in the `x-api-key` header ([get a key](https://app.companydata.com/signup-api)).

Claude Code:

```bash
claude mcp add --transport http companydata https://companydata.com/mcp/ --header "x-api-key: your-api-key-here"
```

Cursor (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "companydata": {
      "url": "https://companydata.com/mcp/",
      "headers": { "x-api-key": "your-api-key-here" }
    }
  }
}
```

## Local (npx)

Requires Node.js 18+.

```json
{
  "mcpServers": {
    "companydata": {
      "command": "npx",
      "args": ["-y", "@companydata/mcp-server"],
      "env": { "COMPANYDATA_API_KEY": "your-api-key-here" }
    }
  }
}
```

## Build from source

```bash
git clone https://github.com/companydatacom/companydata-mcp-server.git
cd companydata-mcp-server
npm install
npm run build
```

## Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `COMPANYDATA_API_KEY` | Yes | Sent as `x-api-key` on every request |
| `COMPANYDATA_API_BASE_URL` | No | API origin, default `https://app.companydata.com` (no trailing slash) |

Copy `.env.example` to `.env` for local testing with `npm run dev` (load env in shell: `set -a && source .env && set +a && npm run dev`).

## Tools

| Tool | API |
|------|-----|
| `company_search` | `GET /api/company/search` |
| `company_enrich` | `GET /api/company/export` with `ID` and `export=true` |
| `field_lookup` | `GET /api/cities` |

## Cursor & Claude Desktop

1. Build the project (`npm run build`).
2. In your MCP host (e.g. **Cursor Settings → MCP** or Claude Desktop config), add a server (adjust paths):

```json
{
  "mcpServers": {
    "companydata": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/companydata-mcp-server/dist/index.js"],
      "env": {
        "COMPANYDATA_API_KEY": "your-api-key-here",
        "COMPANYDATA_API_BASE_URL": "https://app.companydata.com"
      }
    }
  }
}
```

3. Reload MCP / restart Cursor if needed.

## Smoke checklist

- Server starts without errors (`npm run build && node dist/index.js` with env set).
- MCP host lists tools: `company_search`, `company_enrich`, `field_lookup`.
- `company_search` returns 200 payload for a simple query (e.g. `search=BoldData`).
- `field_lookup` returns city suggestions (e.g. `search=amst`).

Development without a separate build step:

```json
{
  "mcpServers": {
    "companydata": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/companydata-mcp-server/src/index.ts"],
      "env": {
        "COMPANYDATA_API_KEY": "your-api-key-here",
        "COMPANYDATA_API_BASE_URL": "https://app.companydata.com"
      }
    }
  }
}
```

## CLI

After `npm run build`, the package exposes `companydata-mcp` when linked (`npm link`) or when `node_modules/.bin` is on `PATH`.

## Distribution

- Hosted: `https://companydata.com/mcp/` (Streamable HTTP, stateless). The website serves the same tools from a copy of `src/tools.ts`.
- npm: `@companydata/mcp-server`.
- Official MCP Registry: `com.companydata/mcp` (see `server.json`).

## License

ISC