Pine Assistant MCP

Pine AI is a personal assistant for real-world tasks. This repository provides the Pine Assistant plugin for MCP clients and the earlier local Python stdio server.

Pine Assistant plugin

Pine Assistant (pine) connects a supported client to Pine through a remote MCP server and opens browser-based OAuth authorization when the client connects. Bring Pine AI into your agent to handle real-world tasks and follow up on progress and results. The shared skill guides the agent through the available tools and any details or account actions a task needs.

Install and authorize

Ask your agent to set up Pine:

Read https://pine.im/features/mcp and help me install Pine.

Or follow the instructions for your client below.

Install Pine Assistant (pine) from the Pine AI (pine-ai) marketplace, then begin a new conversation. Connect and complete the Pine browser authorization when your client asks.

Codex

codex plugin marketplace add https://github.com/19PINE-AI/pine-mcp-server.git --ref main
codex plugin add pine@pine-ai

To update it:

codex plugin marketplace upgrade pine-ai
codex plugin add pine@pine-ai

Claude Code

claude plugin marketplace add https://github.com/19PINE-AI/pine-mcp-server.git
claude plugin install pine@pine-ai

To update it:

claude plugin marketplace update pine-ai
claude plugin update pine@pine-ai

Use Pine naturally after authorizing, for example:

Use Pine to contact a nearby bike repair shop and ask about tune-up availability.

Pine keeps working after you leave. Ask your agent for progress or results when you return. Complete payment, account connection, or phone verification in Pine when the task directs you there.

In Codex, use $pine to load the shared guidance. In Claude Code, use /pine:pine.

Connect from another MCP client

Add a Streamable HTTP MCP server with this configuration, then use the client's Connect or Authorize control to complete OAuth in a browser:

{
  "mcpServers": {
    "pine": {
      "type": "http",
      "url": "https://mcp.pine.im/mcp"
    }
  }
}

Cursor

Cursor supports the Pine Assistant plugin and a manual MCP connection.

For a local native plugin install, clone this repository, copy plugins/pine to ~/.cursor/plugins/local/pine, and reload Cursor:

git clone https://github.com/19PINE-AI/pine-mcp-server.git
mkdir -p ~/.cursor/plugins/local
cp -R pine-mcp-server/plugins/pine ~/.cursor/plugins/local/pine

Use Developer: Reload Window, then enable Pine in Customize and complete browser authorization. When updating, replace the existing local pine folder instead of copying a second pine folder inside it. Team administrators can also import this repository as a marketplace.

For a manual connection, add the Streamable HTTP configuration above in Cursor's MCP settings, then use its authorization control.

Legacy local stdio server

The published pine-mcp-server Python package is separate from the plugin distribution: pip and uvx do not install the client plugin. It runs a local stdio MCP server backed by the pine-assistant SDK.

Install it with pip:

pip install pine-mcp-server

Or run it without installing:

uvx pine-mcp-server

Configure a stdio MCP client with the executable and Pine credentials. For example:

{
  "mcpServers": {
    "pine-assistant": {
      "command": "uvx",
      "args": ["pine-mcp-server"],
      "env": {
        "PINE_ACCESS_TOKEN": "your-access-token",
        "PINE_USER_ID": "your-user-id"
      }
    }
  }
}

If installed with pip, use pine-mcp-server as command and omit args. Alternatively, authenticate with the pine_auth_request_code and pine_auth_verify_code tools. Do not put access tokens in plugin files.

Environment

Variable	Required	Description
PINE_ACCESS_TOKEN	Yes*	Pine AI access token
PINE_USER_ID	Yes*	Pine AI user ID
PINE_BASE_URL	No	Pine AI backend URL (default: https://www.19pine.ai)
PINE_DEVICE_ID	No	Stable device identifier for subprocess clients; otherwise a new ID may be generated when ~/.pine/device_id is unwritable.

* Not required when authenticating at runtime with the auth tools.

Tools

Area	Tools
Authentication	pine_auth_request_code, pine_auth_verify_code
Sessions	pine_session_create, pine_session_list, pine_session_get, pine_session_delete, pine_session_url
Conversation	pine_get_history, pine_send_message, pine_send_form_response, pine_send_auth_confirmation, pine_send_location_response, pine_send_location_selection
Tasks	pine_task_start, pine_task_stop
Attachments	pine_upload_attachment, pine_delete_attachment
Social and scheduling	pine_social_share, pine_update_call_reminder

The local server follows a load-conversation model: create or select a session, send a message, and read history for subsequent questions and results. It does not stream real-time updates.

Releases

Plugin releases use immutable plugin-vX.Y.Z tags. The Python package uses vX.Y.Z tags and is published independently to PyPI. Keep all plugin manifest versions synchronized before creating a plugin tag. Plugin tags run validation without publishing to PyPI. Python tags must match the version in pyproject.toml before publication.

The installation commands track main. Merge and validate a release before tagging it, bump plugin versions when changing the package, and never move an existing release tag. To pin a plugin release in Codex, add the repository with --ref plugin-vX.Y.Z instead of --ref main. After updating a plugin, start a new client conversation (or reload the client) to load its changes.

Development

For plugin testing, clone this repository and edit plugins/pine/.mcp.json in that working copy to point at the endpoint under test. Do not commit a local endpoint or credentials. Use separate client configuration directories so the local marketplace does not collide with your normal Pine installation.

From the repository root, test Codex:

PINE_CODEX_TEST_CONFIG="$(mktemp -d)"
CODEX_HOME="$PINE_CODEX_TEST_CONFIG" codex plugin marketplace add .
CODEX_HOME="$PINE_CODEX_TEST_CONFIG" codex plugin add pine@pine-ai
CODEX_HOME="$PINE_CODEX_TEST_CONFIG" codex

Or Claude Code:

PINE_CLAUDE_TEST_CONFIG="$(mktemp -d)"
CLAUDE_CONFIG_DIR="$PINE_CLAUDE_TEST_CONFIG" claude plugin marketplace add .
CLAUDE_CONFIG_DIR="$PINE_CLAUDE_TEST_CONFIG" claude plugin install pine@pine-ai
CLAUDE_CONFIG_DIR="$PINE_CLAUDE_TEST_CONFIG" claude

Keep the same temporary directory while testing. Each isolated client may require its own client login and Pine authorization. Remove the temporary configuration after testing; do not copy credentials into the repository.

Validate the Claude package and marketplace with:

claude plugin validate plugins/pine --strict
claude plugin validate . --strict

CI also checks cross-client metadata and bundled paths. For the legacy Python server's development dependencies:

pip install -e ".[dev]"

License

MIT