Sherlog

Sherlog MCP Server gives you a persistent, session-aware IPython workspace that can host multiple concurrent sessions and easily integrate external MCP servers. It emphasizes a lean tool surface, persistent state, and DataFrame-oriented results so you can build complex analyses by composing small, well-scoped actions inside a secure, reproducible environment.

How to use

You interact with the server through an MCP client that connects over HTTP transport or via local STDIO tooling. Start a session, run commands, and leverage built-in tools to execute CLI commands or Python code inside a persistent IPython shell. You can plug in external MCP servers so their results automatically appear in the same workspace and as DataFrames for easy slicing, filtering, and subsequent analysis. Use call_cli to run shell commands and execute_python_code to run Python snippets. When you add external MCPs, prefix their results in the namespace with external_ so you can combine data from multiple sources in a single notebook session.

How to install

Prerequisites: you need Docker Desktop to run the MCP server.

1. Create a working directory for your MCP project and navigate into it.

2. Prepare environment variables for core settings and any external MCPs you plan to use.

3. Start the server container with your chosen configuration. The server supports persistent sessions and multiple container variants for different development needs.

Configuration and external integrations

You can connect external MCP servers to run within the same IPython workspace. External tools are automatically integrated into the IPython namespace and their results are converted to DataFrames for subsequent operations.

For example, you can add external MCP servers for a filesystem-like tool and a Postgres-backed tool, so their outputs appear as external_filesystem and external_postgres in your session.

Advanced usage

External MCPs are prefixed in the namespace (for example, external_[server]_[tool]). This makes it easy to combine results from multiple data sources without cluttering the main tool surface.

All results are stored as DataFrames, so you can inspect, slice, and join them to drive further analysis. The persistent IPython shells maintain separate workspaces per session, and you can manage up to four concurrent sessions.

Notes on security and persistence

OAuth integration is available for Google Workspace services. Tokens are encrypted and refreshed automatically as needed. Persistent session storage is kept in a dedicated data folder to ensure shells survive container restarts.

Example configuration for external MCPs

You can wire an external filesystem-like MCP and a Postgres MCP as shown in the configuration example. Both run under npx and expose their results as DataFrames in the IPython workspace.

{
  "filesystem": {
    "type": "stdio",
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  },
  "postgres": {
    "type": "stdio",
    "name": "postgres",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "$DATABASE_URL"
    }
  }
}

Troubleshooting

If sessions fail to persist across restarts, verify that the data directory used for session storage is writeable and mounted correctly in your deployment environment. Check that external MCPs are reachable and that their command invocations match the specified npx style commands exactly.

Available tools

call_cli

Execute shell commands from within the IPython session. The output is captured and presented as a DataFrame for further processing.

execute_python_code

Run Python code inside the persistent IPython shell. Results are stored in the session namespace as DataFrames when applicable.

external_filesystem

External MCP tool that exposes filesystem-like operations and returns results as DataFrames in the IPython workspace.

external_postgres

External MCP tool that runs Postgres-related operations via MCP and returns results as DataFrames in the IPython workspace.