npm package: @impart-security/impart-mcp
Description: Model Context Protocol (MCP) implementation for interacting with Impart's API
Author: Impart Security
Latest version: 0.2.3


# Impart MCP Tools

A Model Context Protocol (MCP) implementation for interacting with Impart's API. This package provides a set of tools for managing and interacting with Impart's security features through MCP.

## Features

- Rules Script Management
- Rule Recipe Management
- API Bindings Management
- Endpoint Inventory
- Tag Management
- Observed Hosts Monitoring
- Specification Management
- List Management
- Inspector Management


## Prerequisites

You'll need to set up the following environment variables:

- `IMPART_AUTH_TOKEN` - Your Impart authentication token

## Available Tools

This MCP server provides **26 tools** for managing Impart Security through the Model Context Protocol. All tools are automatically suffixed with the last 4 characters of your organization ID (e.g., if your org ID ends with `d3ce`, the tool appears as `list_inspectors_d3ce`).

### Inspectors
- **`list_inspectors`** - Get a list of inspectors for the organization

### Rules Scripts
- **`list_rules_scripts`** - Get a list of rules scripts with filtering options (type, labels, disabled status)
- **`get_rules_script`** - Get details of a specific rules script including source code and revisions

### Rule Recipes (AI-Powered)
- **`list_rule_recipes`** - Get a list of rule recipes with search filtering
- **`get_rule_recipe`** - Get complete details of a specific rule recipe including components
- **`generate_rule_recipe`** ✨ - Generate rule recipe configurations using Impart's AI (Sparkle)
- **`create_rule_recipe`** - Create a new rule recipe from a configuration (typically from generate_rule_recipe)

### API Specs & Endpoints
- **`list_specs`** - Get a list of API specifications with search filtering
- **`get_spec`** - Get details of a specific API spec including revision history
- **`list_endpoints`** - Get inventory of API endpoints with extensive filtering (deprecated status, source, tags, methods, labels)

### API Bindings
- **`list_api_bindings`** - Get a list of API bindings with filtering by spec or collection
- **`create_api_binding`** - Create new API bindings for connecting specs to infrastructure

### Tags & Metrics
- **`list_tags`** - Get a list of tags with label filtering
- **`get_tag_metrics`** - Get timeseries metrics for tags (HTTP requests, attacks, blocks, etc.) with flexible time ranges and rollup options

### Observed Hosts
- **`list_observed_hosts`** - Get a list of observed hosts in your infrastructure
- **`get_observed_host`** - Get detailed information about a specific observed host

### Lists (Allow/Block Lists)
- **`list_lists`** - Get a list of lists with filtering by kind (ip, string, uuid, country, path, asn), subkind, and labels
- **`get_list_items`** - Get items from a specific list with pagination
- **`create_list`** - Create new lists for IP addresses, strings, UUIDs, countries, paths, or ASNs
- **`update_list_items`** - Update items in an existing list

### Labels
- **`list_labels`** - Get a list of labels with search filtering
- **`create_label`** - Create new labels with customizable colors and display names

### Test Cases
- **`list_test_cases`** - Get a list of rules test cases for validating rule behavior
- **`get_test_case`** - Get detailed information about a specific test case

### HTTP Requests (Traffic Analysis)
- **`get_requests`** - Get HTTP requests captured by Impart with extensive filtering options:
  - Time ranges (relative like `-1d`, `-24h` or absolute timestamps)
  - Status codes, tags, IPs, external request IDs, rule IDs
  - API specs, collections, endpoints
  - Pagination with up to 1000 results per request
  - Sort order (ascending/descending)
  - Data source selection (PostgreSQL or ClickHouse)
- **`get_request_details`** - Get complete details of a specific HTTP request including headers, body, and processing information

## Connecting to MCP Clients


### Claude Desktop

To use Impart MCP with Claude Desktop, you'll need to configure the MCP server in Claude's configuration file. Here's how:

1. Open or create your Claude Desktop configuration file:
```sh
   # MacOS
   vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   # %AppData%\Claude\claude_desktop_config.json
```

2. Add the Impart MCP server configuration:
```json
   {
       "mcpServers": {
           "impart": {
               "command": "npx",
               "args": [
                   "@impart-security/impart-mcp"
               ],
               "env": {
                   "IMPART_AUTH_TOKEN": "your_auth_token"
               }
           }
       }
   }
```

   Make sure to update the environment variables with your Impart credentials.

3. Restart Claude Desktop for the changes to take effect.

The Impart MCP tools will now be available in your Claude Desktop conversations. You can use them to manage rules scripts, API bindings, endpoints, and more directly from Claude.

### Cursor

To use Impart MCP with Cursor, create or edit the `mcp.json` file in your Cursor configuration directory:

```sh
# MacOS
vim ~/Library/Application\ Support/Cursor/mcp.json

# Windows
# %AppData%\Cursor\mcp.json
```

Add the Impart MCP server configuration:

```json
{
  "mcpServers": {
    "impart": {
      "command": "npx",
      "args": ["@impart-security/impart-mcp"],
      "env": {
        "IMPART_AUTH_TOKEN": "your_auth_token"
      }
    }
  }
}
```

Make sure to update the environment variables with your Impart credentials.

### Claude Code

**Quick setup:**

```sh
claude mcp add --transport stdio --env IMPART_AUTH_TOKEN=your_auth_token impart -- npx @impart-security/impart-mcp
```

**Recommended setup** (keeps the token in your shell profile instead of a config file):

1. Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
```sh
export IMPART_AUTH_TOKEN=your_auth_token
```

2. Add to your project's `.mcp.json`:
```json
{
  "mcpServers": {
    "impart": {
      "command": "npx",
      "args": ["@impart-security/impart-mcp"],
      "env": {
        "IMPART_AUTH_TOKEN": "${IMPART_AUTH_TOKEN}"
      }
    }
  }
}
```

Verify the connection by running `/mcp` inside Claude Code.

## Documentation

For complete documentation including setup guides, available tools, and troubleshooting, visit the [Impart MCP documentation](https://docs.impartsecurity.net/docs/integrations/mcp).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

When contributing:
1. Run `npm run build` to compile
2. Run `cd testing && ./test-all.sh` to verify tests pass
3. Add tests for new features or bug fixes
4. Update documentation

## License

Apache-2.0

## Support

For support, please contact Impart support or open an issue on GitHub.