Metadata-Version: 2.4
Name: grounded-mcp
Version: 0.1.0
Summary: MCP server for real-time package versions, download counts, and service status. Covers 1,000+ npm/PyPI packages and 76 cloud services.
Project-URL: Homepage, https://grounded-api.dev
Project-URL: Repository, https://github.com/nghizas/grounded-mcp
Project-URL: Documentation, https://grounded-api.dev
Project-URL: Bug Tracker, https://github.com/nghizas/grounded-mcp/issues
Author-email: Grounded <hello@grounded-api.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,grounded,mcp,model-context-protocol,package-version,service-status
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# grounded-mcp

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)
