Content
# Steampipe MCP Server
An MCP server interacting with PostgreSQL databases, primarily for use with [Steampipe](https://steampipe.io/).
Steampipe has a schema per connection, and creates a search_path that includes all the schemas, but public schema is typically empty. In additiona to that, Steampipe plugins for AWS, GCP and other clouds have a lot of tables, so just listing all of them is not practical. So, the recommended way to prompt your Claude Desktop would be to say something like this: "In steampipe using aws_all schema, give me a list of all ec2 instances". This way Claude will be more likely to use list_tables_in_schema in schema command, to limit the number of tables retrieved.
## Prerequisites
### 1. Install Steampipe
**macOS:**
```bash
brew tap turbot/tap
brew install steampipe
```
**Linux:**
```bash
sudo /bin/sh -c "$(curl -fsSL https://steampipe.io/install/steampipe.sh)"
```
**Windows:**
```bash
iwr -useb https://steampipe.io/install/steampipe.ps1 | iex
```
### 2. Start Steampipe Service
Start Steampipe as a background service:
```bash
steampipe service start
```
You can verify the service is running with:
```bash
steampipe service status
```
### 3. Get Database URL
The Steampipe PostgreSQL connection string can be found:
```bash
steampipe service status
```
Look for the `Database URL` in the output, which typically looks like:
```
postgres://steampipe:password@localhost:9193/steampipe
```
You can provide this URL in the `--database-url` argument when running the server:
```
steampipe-mcp-server --database-url postgresql://steampipe:password@localhost:9193/steampipe
```
Note: Protocol must be `postgresql://` for the server to work correctly.
### 4. Configuring Environment Variables
You can configure the database connection using an environment variable instead of passing it each time:
1. Create a `.env` file in the project directory with your database URL:
```
STEAMPIPE_MCP_DATABASE_URL=postgresql://steampipe:password@localhost:9193/steampipe
```
2. The server will automatically load this configuration when starting up.
### 5. Install in Claude Desktop
For the published version, you can configure Claude Desktop directly:
1. Open Claude Desktop
2. Navigate to Settings > Developer > Edit Config
3. Add the following configuration to the JSON file:
```json
{
"mcpServers": {
"steampipe": {
"command": "uvx",
"args": [
"steampipe-mcp-server",
"--database-url",
"postgresql://steampipe:password@localhost:9193/steampipe"
]
}
}
}
```
4. Save the config file and restart Claude Desktop
Replace the database URL with your actual Steampipe database URL. This configuration uses `uvx` to execute the published package directly.
The tools will be available within Claude under the `steampipe` namespace.
## Available Tools
This MCP server provides several useful tools for interacting with your PostgreSQL database:
### `query`
Runs a read-only SQL query against the database and returns results as JSON.
### `list_all_tables`
Lists all available tables in all schemas in your database's search path. Steampipe doesn't use `public` schema, there is schema per connection.
### `list_tables_in_schema`
Lists all tables within a specific schema. Useful to limit the amount of tables, especially when working with just one schema.
### `get_table_schema`
Retrieves column names and data types for a specific table, table should be in a format like `schema.table`.
## Installation
### Development Setup (Recommended)
The easiest way to get started is to use the included Makefile:
```bash
# Create a virtual environment first
uv venv
# Install development dependencies
make dev-install
# View all available commands
make help
```
Alternatively, you can:
1. Clone the repository
2. Create a virtual environment: `uv venv`
3. Activate the environment: `source .venv/bin/activate` (Linux/macOS) or `.venv\Scripts\activate` (Windows)
4. Install dev dependencies: `uv pip install -e .[dev]`
## Development
### Using the Makefile
The project includes a Makefile with common tasks:
```bash
# Run the server in development mode with Inspector
make dev
# Run tests
make test
# Run linting
make lint
# Run type checking
make typecheck
# Format code
make format
# Run all checks (lint and typecheck)
make check
# Install in Claude Desktop
make install-mcp
```
Run `make help` to see all available commands.
## How to Run
### 1. Development Mode (Recommended)
```bash
# Using make
make dev
# OR manually
mcp dev src/steampipe_mcp_server/cli.py
```
This will start the server and the MCP Inspector, allowing you to test the `query` tool and other tools interactively.
### 2. Using CLI
After installation:
```bash
# Using make
make server
# OR with explicit URL
steampipe-mcp-server --database-url postgresql://steampipe:password@localhost:9193/steampipe
# OR with environment variable
export STEAMPIPE_MCP_DATABASE_URL=postgresql://steampipe:password@localhost:9193/steampipe
steampipe-mcp-server
```
## Testing
Run tests with:
```bash
# Using make
make test
# OR manually
pytest
```
For tests that require a database connection, set the `TEST_DB_URL` environment variable.
## Contributing
1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Run tests and checks: `make check test`
5. Submit a pull request
## Releasing
To release a new version of the package:
1. Update the version in `pyproject.toml`
2. Run all checks to ensure everything is working:
```bash
make check test
```
3. Tag the release on GitHub:
```bash
git tag v0.1.0 # Use appropriate version number
git push origin v0.1.0
```
