Metadata-Version: 2.5
Name: acuris-mcp
Version: 1.1.1
Summary: MCP server for Acuris address validation, autocomplete & geocoding — 240+ countries, Royal Mail PAF (UK), free US/Canada census enrichment. Runs against your own Acuris API key.
Project-URL: Homepage, https://www.acuris-geo.com/
Project-URL: Documentation, https://api.acuris-geo.com/docs/mcp
Project-URL: Repository, https://github.com/Acuris-GmbH/acuris-mcp
Author-email: Acuris GmbH <support@acuris-geo.com>
License: MIT
License-File: LICENSE
Keywords: address-autocomplete,address-validation,autocomplete,census,fips,geocoding,mcp,model-context-protocol,reverse-geocoding,royal-mail-paf,typeahead
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.10
Description-Content-Type: text/markdown

# Acuris Geo MCP Server

Give any AI agent — Claude, Cursor, ChatGPT, Gemini CLI and every other
[MCP](https://modelcontextprotocol.io)-capable client — direct, self-describing
access to **Acuris address validation and geocoding**: 240+ countries, honest
`verified` / `corrected` / partial verdicts, UK addresses against the official
Royal Mail PAF (UDPRN + UPRN), and **free census & geographic enrichment** for
street-accurate USA/Canada matches (census tract, block group, FIPS, CBSA/MSA,
congressional district, school district — Canadian equivalents included).

The server is a thin layer **on top of the Acuris REST API**: every tool call
is billed, refunded and rate-limited exactly like the API call it wraps, under
**your own API key**. Failed lookups are refunded automatically — you pay for
results, not attempts.

## Quick start — hosted endpoint (recommended, zero install)

**Claude Code**

```bash
claude mcp add --transport http acuris-geo https://api.acuris-geo.com/mcp \
  --header "Authorization: Bearer YOUR_ACURIS_API_KEY"
```

**Claude Desktop / any JSON-config client**

```json
{
  "mcpServers": {
    "acuris-geo": {
      "type": "http",
      "url": "https://api.acuris-geo.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACURIS_API_KEY" }
    }
  }
}
```

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

```json
{ "mcpServers": { "acuris-geo": {
    "url": "https://api.acuris-geo.com/mcp",
    "headers": { "Authorization": "Bearer YOUR_ACURIS_API_KEY" } } } }
```

**No API key yet?** Connect without one and call the `request_trial_key` tool
with your email — you get an instant free evaluation key (1,000 lookups plus 50 UK
lookups, valid 30 days, no card, no signup form). Before the key is issued the user must agree to the
[Terms of Service](https://api.acuris-geo.com/legal/terms) and the
[UK PAF Evaluation Terms](https://api.acuris-geo.com/legal/uk-evaluation-terms);
the tool asks for that confirmation first. Then reconnect with the key.

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `validate_address` | Validate & standardize one address (240+ countries; UK via Royal Mail PAF with UDPRN + UPRN). Street-accurate USA/Canada matches include the free census enrichment block. | 1 credit |
| `validate_addresses_batch` | Up to 50 addresses per call, mixed countries. Results in input order. | 1 credit / row |
| `enrich_us_ca_address` | Address → census tract, block group, county/state FIPS, CBSA/MSA, congressional district, school district (USA) / dissemination area, census division, CMA/CA, federal electoral district (Canada). | 1 credit (enrichment free) |
| `autocomplete_address` | Address autocomplete (type-ahead): ranked suggestions for a partial input (UK: postcode-first, via Royal Mail PAF). Pick one, then `validate_address` it. | billed like the autocomplete endpoint |
| `geocode_address` | Forward geocoding with an explicit `accuracy_type` on every result. | 1 credit |
| `reverse_geocode` | Coordinates → nearest addresses with distances. | 1 credit |
| `expand_uk_postcode` | UK postcode → every Royal Mail delivery point (organisation, UDPRN, UPRN, rooftop coordinates). | 1 credit / postcode |
| `check_balance` | Remaining credit balances for the connected key. | free |
| `request_trial_key` | Instant free evaluation key by email (idempotent for 24h). | free |

No-match and error responses are **refunded automatically**.

## Local (stdio) mode

```bash
pip install acuris-mcp        # or: uvx acuris-mcp --stdio
ACURIS_API_KEY=YOUR_KEY acuris-mcp --stdio
```

Claude Desktop stdio config:

```json
{
  "mcpServers": {
    "acuris-geo": {
      "command": "uvx",
      "args": ["acuris-mcp", "--stdio"],
      "env": { "ACURIS_API_KEY": "YOUR_KEY" }
    }
  }
}
```

Same tools, same billing. The hosted endpoint is recommended — zero install
and always current.

## Docs & links

- Full MCP docs: https://api.acuris-geo.com/docs/mcp
- REST API reference: https://api.acuris-geo.com/docs
- Pricing: https://www.acuris-geo.com/acuris-pricing/
- US/Canada enrichment: https://www.acuris-geo.com/us-canada-address-enrichment/
- Excel add-in (same engine, no code): https://www.acuris-geo.com/excel-add-in/

## License

MIT (this connector). The Acuris API itself is a commercial service —
see the [terms](https://api.acuris-geo.com/docs/legal-terms).
