Skip to main content
Glama
Sign In
Avanti Fellows PostgreSQL MCP Server

Avanti Fellows PostgreSQL MCP Server

Official
by avantifellows
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Avanti Fellows PostgreSQL MCP Server

Read-only MCP server for querying the Avanti Fellows DB Service (PostgreSQL).

What is this?

This is an MCP (Model Context Protocol) server that lets Claude Code, Cursor, and other AI tools query our PostgreSQL database directly. It's read-only - no writes allowed.

Related MCP server: MCP Server for Database

Available Tools

Tool

Description

query

Run any SELECT query

list_tables

List all tables in the database

describe_table

Get column info, primary keys, foreign keys

sample_data

Get sample rows from a table

count_rows

Count rows with optional WHERE clause

search_columns

Find columns by name across all tables

Installation

1. Install the package

pip install git+https://github.com/avantifellows/mcp-postgres.git

2. Set up credentials

Add these to your shell profile (~/.zshrc or ~/.bashrc):

export AF_DB_HOST="af-database-host"
export AF_DB_PORT="5432"
export AF_DB_USER="your_username"
export AF_DB_PASSWORD="your_password"
export AF_DB_NAME="database_name"

Then reload: source ~/.zshrc

3. Configure your AI tool

Claude Code

claude mcp add avanti-db -- avanti-mcp-postgres

Verify it's working:

claude mcp list

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "avanti-db": {
      "command": "avanti-mcp-postgres",
      "env": {
        "AF_DB_HOST": "af-database-host",
        "AF_DB_PORT": "5432",
        "AF_DB_USER": "your_username",
        "AF_DB_PASSWORD": "your_password",
        "AF_DB_NAME": "database_name"
      }
    }
  }
}

Usage Examples

Once configured, just ask Claude/Cursor about the database:

"What tables are in the database?"
"Show me the schema for the students table"
"How many users signed up this month?"
"Find all columns with 'email' in the name"
"What does the enrollment data look like?"

Updating

pip install --upgrade git+https://github.com/avantifellows/mcp-postgres.git

Local Development

# Clone the repo
git clone https://github.com/avantifellows/mcp-postgres.git
cd mcp-postgres

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in dev mode
pip install -e .

# Create .env file with credentials
cp .env.example .env
# Edit .env with your credentials

# Test the server
avanti-mcp-postgres

Security Notes

  • This server is read-only - INSERT, UPDATE, DELETE are blocked

  • Uses your personal database credentials

  • Queries are logged locally but not sent anywhere

  • Don't commit credentials to git

Troubleshooting

"Connection refused"

  • Check that AF_DB_HOST is correct and accessible from your network

  • Verify you're on VPN if required

"Authentication failed"

  • Double-check AF_DB_USER and AF_DB_PASSWORD

  • Ensure your user has SELECT permissions

Server not showing in Claude Code

  • Run claude mcp list to check status

  • Try removing and re-adding: claude mcp remove avanti-db && claude mcp add avanti-db -- avanti-mcp-postgres

Available Tools

6 tools
count_rowsA

Count rows in a table, optionally with a WHERE clause.

Args:
    table_name: Name of the table
    schema_name: Schema name (default: public)
    where: Optional WHERE clause (without 'WHERE' keyword)

Returns:
    JSON with count

Inputs: table_name (required), schema_name, where. Returns: result

describe_tableA

Get detailed schema information for a table.

Returns column names, types, nullability, and defaults.
Use this to understand table structure before querying.

Args:
    table_name: Name of the table
    schema_name: Schema name (default: public)

Returns:
    JSON with columns, primary keys, and foreign keys

Inputs: table_name (required), schema_name. Returns: result

list_tablesA

List all tables in the database.

Returns tables from all schemas (excluding system schemas).
Use this to discover what data is available.

Returns:
    JSON array of tables with schema, name, and type

Inputs: no named parameters. Returns: result

queryA

Execute a read-only SQL query against the database.

Only SELECT queries are allowed. Use this to explore data,
debug issues, or validate assumptions about the data.

Args:
    sql: A SELECT query to execute

Returns:
    JSON array of results, or error message

Inputs: sql (required). Returns: result

sample_dataA

Get sample rows from a table.

Useful for understanding what data looks like without
writing a full query.

Args:
    table_name: Name of the table
    schema_name: Schema name (default: public)
    limit: Number of rows to return (default: 10, max: 100)

Returns:
    JSON array of sample rows

Inputs: table_name (required), schema_name, limit. Returns: result

search_columnsA

Search for columns by name across all tables.

Useful when you know a column name but not which table it's in.

Args:
    search_term: Partial column name to search for (case-insensitive)

Returns:
    JSON array of matching columns with their tables

Inputs: search_term (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: count_rows counts rows, describe_table provides schema details, list_tables enumerates tables, query executes SQL, sample_data retrieves sample rows, and search_columns finds columns by name. The descriptions reinforce these unique functions, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, such as count_rows, describe_table, list_tables, query, sample_data, and search_columns. This uniformity makes the tool set predictable and easy to navigate for an agent.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a PostgreSQL exploration and querying purpose. Each tool earns its place by covering essential database operations like discovery, inspection, and data retrieval without being overly complex or sparse.

    Completeness4/5

    The tool set provides strong coverage for exploring and querying a PostgreSQL database, including discovery (list_tables, search_columns), inspection (describe_table), and data retrieval (count_rows, sample_data, query). A minor gap is the lack of write operations (e.g., insert, update, delete), but this aligns with a read-only focus, and agents can work around it for analysis tasks.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP PostgreSQL

      cuevacelis
      A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for PostgreSQL that enables safe database introspection and querying via natural language.
      468 npm
      MIT

    • safe-postgres-mcp

      samuel-cabral
      A
      license
      Not graded
      quality
      D
      maintenance
      A zero-config, read-only PostgreSQL MCP server that enforces read-only access at the database level using READ ONLY transactions, allowing AI agents to safely explore schemas and run SELECT queries without risk of mutation.
      16 npm
      MIT

    • mcp-postgres

      imangali01
      F
      license
      Not graded
      quality
      B
      maintenance
      Read-only MCP server for PostgreSQL enabling schema introspection and SELECT queries via MCP clients like Claude, with multi-layered write protection.
      -