# grounded-mcp

<!-- mcp-name: io.github.nghizas/grounded -->

MCP server for real-time package versions, download counts, and service status — powered by [Grounded](https://grounded-api.dev).

Tracks 1,000+ npm and PyPI packages and 76 cloud services. No signup required.

## Install

### Claude Code

```bash
claude mcp add grounded -- uvx grounded-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "grounded": {
      "command": "uvx",
      "args": ["grounded-mcp"]
    }
  }
}
```

### Cursor

Add to your MCP settings:

```json
{
  "grounded": {
    "command": "uvx",
    "args": ["grounded-mcp"]
  }
}
```

## Tools

| Tool | Description | Example |
|------|-------------|---------|
| `check_package_version` | Latest version of an npm or PyPI package | `check_package_version("react")` |
| `check_downloads` | Weekly download count | `check_downloads("flask", registry="pypi")` |
| `check_service_status` | Cloud service operational status | `check_service_status("github")` |
| `lookup_fact` | General-purpose fact lookup | `lookup_fact("npm", "react", "license")` |

### Available fields

For npm/PyPI packages: `latest_version`, `license`, `deprecated`, `dep_count`, `required_runtime`, `weekly_downloads`

For services: `status`

## Configuration

Works out of the box with no API key (50 lookups/day per IP).

For higher limits, set `GROUNDED_API_KEY`:

```bash
claude mcp add grounded -e GROUNDED_API_KEY=your_key -- uvx grounded-mcp
```

Sign up for a free API key (1,000 req/day) at https://grounded-api.dev.

## Example

Ask your AI assistant:

> "What's the latest version of React?"

The assistant calls `check_package_version("react")` and gets:

```
Value: 19.2.4
Source: https://registry.npmjs.org/react
Fetched at: 2026-03-06T12:00:00Z
Hash: sha256:a1b2c3...
Tier: warm (TTL: 300s)
```

## Links

- [Grounded website](https://grounded-api.dev)
- [REST API](https://api.grounded-api.dev/v1/npm/react/latest_version)
- [CLI tool](https://www.npmjs.com/package/grounded-cli)