Content
# DataImpulse MCP Proxy
Use DataImpulse residential proxy targeting from Claude Code or OpenCode without routing the rest of your system through a proxy. This educational MCP server provides bounded access to public HTTP(S) pages with best-effort SSRF safeguards.
> [!WARNING]
> Never configure `HTTP_PROXY` or `HTTPS_PROXY` globally. This server creates a DataImpulse `ProxyAgent` for each MCP request, so other terminals, editors, package managers, and MCP servers remain unaffected.
## Quick Start
**Prerequisites:** Node.js 22.19.0 or later and a DataImpulse account with a username and password.
```bash
git clone https://github.com/Gentleman-Programming/dataimpulse-mcp.git
cd dataimpulse-mcp
npm install
```
The server reads only `DI_USER` and `DI_PASS` at runtime. Copy `.env.example` for local reference if useful, but configure credentials in your MCP client rather than committing a `.env` file.
## Connect Clients
### Claude Code
Run this from the checked-out repository, replacing the placeholders and path:
```bash
claude mcp add di-proxy --scope user \
--env DI_USER=your_dataimpulse_username \
--env DI_PASS=your_dataimpulse_password \
-- node /absolute/path/to/dataimpulse-mcp/index.js
```
`--scope user` makes the server available to your local Claude Code user. Claude Code stores this configuration, including the supplied credentials, in `~/.claude.json`; protect that file and never commit or share it.
### OpenCode
Add this entry to your OpenCode configuration, replacing the placeholders and absolute path:
```json
{
"mcp": {
"di-proxy": {
"type": "local",
"command": ["node", "/absolute/path/to/dataimpulse-mcp/index.js"],
"environment": {
"DI_USER": "your_dataimpulse_username",
"DI_PASS": "your_dataimpulse_password"
}
}
}
}
```
Restart OpenCode after saving the configuration so it starts the stdio server with the new environment.
## Tool Reference
### `fetch_page`
Fetches a public HTTP(S) page through DataImpulse. By default, it returns cleaned, readable text; set `raw` to `true` when the caller needs HTML.
| Parameter | Required | Description |
| --- | --- | --- |
| `url` | Yes | Public HTTP(S) URL, up to 2,048 characters. URLs with credentials and local/private destinations are rejected. |
| `country` | No | Two-letter ISO country code, such as `US` or `ES`. |
| `city` | No | City token using letters, numbers, hyphens, or underscores. Requires `country`. |
| `session` | No | Stable session token using letters, numbers, hyphens, or underscores. |
| `raw` | No | Set to `true` to return HTML instead of cleaned text. |
```json
{
"url": "https://example.com",
"country": "US",
"session": "research-001"
}
```
```json
{
"url": "https://example.com",
"country": "ES",
"city": "Madrid",
"raw": true
}
```
### `check_exit_ip`
Checks the public exit IP selected by DataImpulse without fetching a target page. Use it to verify country or session targeting before a workflow.
| Parameter | Required | Description |
| --- | --- | --- |
| `country` | No | Two-letter ISO country code. |
| `session` | No | Session token to check a stable route. |
```json
{
"country": "US",
"session": "research-001"
}
```
## Targeting And Errors
**Targeting practices**
- Use an explicit `country` for geo-specific content.
- Reuse the same `session` across multi-step flows that need a consistent route.
- Use `city` only when necessary: DataImpulse charges city targeting at double the normal rate.
- Avoid blind retries. Change one variable, observe the result, and stop when the target rejects the request.
**Error actions**
| Response | Meaning | Action |
| --- | --- | --- |
| `407 TRAFFIC_EXHAUSTED` | DataImpulse traffic credit is exhausted. | Add traffic credit, then retry. |
| `407 THREADS_EXHAUSTED` | The account has more than 2,000 active connections. | Reduce concurrent requests, then retry. |
| `503 NO_RAY` | No proxy IP matches the requested targeting. | Remove city targeting and retain only the country. |
| `403` | The destination blocked the request. | Try another country or a fixed session once; respect the site's rules. |
| `429` | The destination applied rate limiting or anti-bot controls. | Try one new session or another country once. If it persists, access the target site directly or use another search engine. Do not retry blindly. |
## Security Model
- **Best-effort SSRF safeguards:** every initial URL and redirect target is checked for an HTTP(S) scheme, no credentials, a permitted hostname, and public-only local DNS resolution. Local, private, metadata, credentialed, and mixed-resolution hosts are rejected, with a maximum of 10 redirects.
- **Remote proxy resolution:** `ProxyAgent` sends the hostname to the remote proxy, which performs its own DNS resolution. DNS rebinding or split-horizon DNS can therefore differ from local validation. Do not use this tool with untrusted URLs in high-security environments; if exposing it to untrusted users, prefer a domain allowlist.
- **Credentials:** `DI_USER` and `DI_PASS` are read only at startup and are never logged or returned to MCP clients.
- **Response bounds:** bodies with an advertised `Content-Length` above 1,048,576 bytes (1 MiB) are rejected before reading; streaming bodies are cancelled once they exceed that limit. Successful and error output is then limited to 60,000 characters.
- **Timeout:** every request has a 45-second timeout; each per-request proxy agent is destroyed after use.
## License
This project is licensed under the [MIT License](LICENSE).
MCP Store